Search & Paging Syntax

Data retrieval services typically include standard parameters for searching, sorting, and pagination.
  1. Pagination Parameters
  2. Sort Parameters
  3. Search Parameters
  4. Data Types
    1. Date
    2. Datetime
    3. Integer
    4. Decimal
    5. Character
    6. Boolean
    7. NULL
  5. Functions

Pagination Parameters

Pagination allows data to be retrieved in sets of a specified size and provides additional data about the result set.
Parameter Description
_limit Integer > 0 and <= 25 indicating how many results to return at once. The default is 10.
_pagination
  • 0 means don't return the Pagination hash in the response
  • 1 means to return the Pagination hash, which includes the result set size
  • count means to return just the number of rows and omit any individual records from the response. The response will return just the Pagination hash, which includes the result set size
The default is 0.
_page Indicates the page number of the result set to return, where 1 is the first page.
When the Pagination hash is enabled, the response will include the following: 
"Pagination": {
  "TotalRows": 78,
  "PageSize": 25,
  "TotalPages": 4,
  "CurrentPage": 1
}
Attribute Description
TotalRows The total number of rows in the response.
PageSize The number of rows that are returned in a single page.
TotalPages The total number of pages in the response.
CurrentPage The page number of the current response.

Sort Parameters

Sorting is typically available on resources that allow searching.
Parameter Description
_orderby Indicates the order in which to return records in the result set. Each service has its own default order.
Any searchable field can be present in the _orderby parameter, with some exceptions (e.g. longer text fields such as PublicRemarks for listings). To specify "Ascending" or "Descending" order, prefix the field used in the _orderby parameter with the+ and - characters, respectively. Ordering listing results descending by ListPrice 
_orderby=-ListPrice
Ordering listing results by multiple attributes: 
_orderby=-ListPrice,+BathsTotal

Search Parameters

Request parameters below are common to data retrieval services supporting searching.
Parameter Description
_filter Of the format <field> <operator> <condition> [<connector> <field> <operator> <condition>]
The components of a filter string are as follows:
  • connector: used to indicate AND, OR, or NOT operators between multiple fields.
    Connector Description Example
    And Logical conjunction PropertyType Eq 'A' And BathsTotal Eq 3.0
    Or Logical disjunction PropertyType Eq 'A' Or BathsTotal Eq 3.0
    Not Logical negation PropertyType Eq 'A' Not BathsTotal Eq 3.0
  • field: a valid field name for the resource being searched, e.g. ListPrice for listings.
  • operator: One of the following:
    Operator Description Applies To These Data Types Example
    Eq Equal. All BathsTotal Eq 4.0
    Ne Not equal. All City Ne 'Fargo'
    Bt Between. Date, Datetime, Integer, and Decimal BathsTotal Bt 3.0,4.0
    Gt Greater than. Date, Datetime, Integer, and Decimal BathsTotal Gt 2.0
    Ge Greater than or equal to. Date, Datetime, Integer, and Decimal BathsTotal Ge 2.0
    Lt Less than. Date, Datetime, Integer, and Decimal BathsTotal Lt 4.0
    Le Less than or equal to. Date, Datetime, Integer, and Decimal BathsTotal Le 4.0
  • condition: a value of a supported data type, or a function supported by the data type.
_filter supports one level of parameter nesting with parentheses. Valid query with one level of nesting: 
  Field1 Eq 'Value1' And (Field2 Eq 'Value2' Or Field3 Eq 'Value3')
Invalid query with two levels of nesting: 
Field1 Eq 'Value1' And (Field2 Eq 'Value2' Or (Field3 Eq 'Value3' And Field4 Eq 'Value4'))

Data Types

All data values are one of the following defined data types.
Data Type Format Example
Date YYYY-MM-DD 2008-10-31
Datetime YYYY-MM-DDThh:mm:ss.uuuuuu 2003-04-01T13:01:02.571752
Integer A number no decimal component 142
Decimal A number with X (0-N) decimal places 142.01
Character An alphanumeric string, padded with single quotes 'Lorem O\'Little Ipsum'
Boolean true or false true
NULL NULL NULL

Date

Example: 2008-10-31

The Date type follows ISO 8601.

Datetime

Example: 2003-04-01T13:01:02.571752

The Datetime type follows ISO 8601, with the addition of the six microsecond digits for more precise timestamps

Integer

Example: 142

The Integer data type specifies a number with no decimal component.

Decimal

Example: 142.01

The Decimal data type specifies a number with a decimal component.

Character

Example: 'Lorem O\'Little Ipsum'

The Character data type specifies a string, and is always padded with single quotes.

Wildcards

The Character data type supports the following two wildcard operators:
Operator Description Example
* Matches zero or more occurrences of any character. 'F*rgo' regex: /F.*rgo/
? Matches zero or one occurrences of any character. 'F?rgo' regex: /F.{1}rgo/
Case-Insensitive Searching
When a wildcard is present, the search criterion will be applied as a case-insensitive match; without a wildcard, it will be case-sensitive.
Note the following restrictions on using wildcards:
  1. A condition may not exist solely of wildcards.
  2. A condition may not include more than three wildcard operators.
  3. Wildcards will be ignored if a list of conditions is used.
  4. Wildcards may only be used with the Eq and Ne operators.

Escaping Special Characters

Any special character (wildcards or a single quote) can be escaped with the backslash character: 
'Lorem O\'Little Ipsum'

Boolean

Example: true

Boolean data types are always either true or false.

NULL

Example: NULL

NULL describes the absence of a value. There are only two use cases for searching using the NULL type:
  1. For the absense of a value, e.g. City Eq NULL
  2. For the precense of a value, e.g. City Ne NULL

Functions

Functions may be used in place of data values for supported data types to provide more flexible searches.
Name Supported Data Type Description Example
now Datetime Use the current time to search on a Datetime field. OriginalEntryTimestamp Lt now()
day Datetime Search on a Datetime field within a range of days from the current date and time. OriginalEntryTimestamp Ge days(-7)