Search & Paging Syntax

This documentation has moved to the Spark Platform website. Please click here to view.


Request parameters below are common to data retrieval services.

Parameter Description
_limit Integer > 0 and <= 25 indicating how many results to return at once. The default is 10.
_expand
  • 0=return just the basic set of data (typically just IDs and names)
  • 1=return the full set of data

Not all services support this parameter; see individual documentation for more details. Some services support specification of what fields to return, such as the Listings service , so _expand also accepts custom parameters such as lists of fields for supporting services. The basic set of data varies depending on the service, so please see the individual service’s definition for more details. The idea is to return a limited set of data for the purpose of displaying a list of items quickly if _expand=0. The default is _expand=0 for services that support this option.

_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. Note that not all services support this, but the Listings service does.

The default is 0.

_page Indicates the page number of the result set to return, where 1 is the first page.
_orderby Indicates the order in which to return records in the result set. Each service has its own default order.

Pagination

The Pagination hash is enabled by sending _pagination=1 on a request. The response will include the following (actual values will differ):

"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. This is equal to the _limit parameter if specified, or if not specified, the default value.
TotalPages The total number of pages in the response.
CurrentPage The page number of the current response, in range from 1 to TotalPages, inclusive.

Search Parameters

Common to all queries:
_filter: of the format <connector> <field> <operator> <condition>

Note that _filter supports one level of parameter nesting with parentheses. That is, a query such as (Field1 Eq Value1 Or Field2 Eq Value2) is valid, while a query such as (Field1 Eq Value Or (Field2 Eq Value And Field3 Eq Value)) is not.

 

  • connector: used to indicate AND or OR operators between multiple fields. This is required between all fields, which means it does not appear before the first field.
    Connector Description Example
    And Logical and PropertyType Eq 'A' And BathsTotal Eq 3.0
    Or Logical or PropertyType Eq 'A' Or BathsTotal Eq 3.0
  • field: whatever the valid field names are for a resource (e.g. ListPrice for listings)
  • operator: One of the following:
    Operator Description Applies To These Data Types Example
    Eq Equal. Accepts wildcards * and ?, up to a maximum of 3 wildcards per operator. A condition may not consist solely of wildcards. All BathsTotal Eq 4.0 ; City Eq 'Fargo'
    Ne Not equal. Accepts wildcards * and ?, up to a maximum of 3 wildcards per operator. A condition may not consist solely of wildcards. All BathsTotal Ne 4.0 ; City Ne 'Fargo'
    Gt Greater than. No more than one condition may be specified for each Gt operator. Date, Datetime, Integer, and Decimal BathsTotal Gt 2.0
    Ge Greater than or equal to. No more than one condition may be specified for each Ge operator. Date, Datetime, Integer, and Decimal BathsTotal Ge 2.0
    Lt Less than. No more than one condition may be specified for each Lt operator. Date, Datetime, Integer, and Decimal BathsTotal Lt 4.0
    Le Less than or equal to. No more than one condition may be specified for each Le operator. Date, Datetime, Integer, and Decimal BathsTotal Le 4.0
  • condition: All strings should be wrapped with single quotes and escaped with a backslash, e.g. O'Leary becomes 'O\'Leary'. Note that the query syntax must match each field’s data type as specified by the Standard Fields service. For example, since BathsTotal is a decimal data type and not an integer, a query of BathsTotal Eq 4 will fail, but BathsTotal Eq 4.0 will succeed.

Data Types:

Data Type Format or Notes Example Needs single quotes? Description
date YYYY-MM-DD 2008-10-31 No Follows ISO 8601
datetime a.k.a. timestamp YYYY-MM-DDThh:mm:ss.uuuuuu 2003-04-01T13:01:02.571752 No Follows ISO 8601, with the addition of the six microsecond digits for more precise timestamps
numberX A number with X (0-N) decimal places 142.01 No A numeric field designed to support any number of decimal places. No commas are allowed.
charX An alphanumeric string with X maximum characters ‘Lorem O\’Little Ipsum’ Yes A text field up to X characters in length. Single quotes within the string are escaped with the backslash () character.
boolean Supports true or false true No A field containing one of two possible values.

Comments on this entry are closed.