Skip to content

Resource Queries

Query Parameter Syntax

The API supports a variety of query parameters to filter and refine your search results. This syntax is consistent across all parameter types, although some operators may not be logically applicable to certain data types.

General Syntax

The general format for query parameters is:

field_name[__operator]=value

Where:

  • field_name is the name of the field you want to filter on
  • __operator is optional and specifies the type of comparison
  • value is the value you want to compare against

Available Operators

Operator Description Example
empty or __eq Equals field=value or field__eq=value
__ne Not Equals field__ne=value
__gt Greater Than field__gt=value
__gte Greater Than or Equal To field__gte=value
__lt Less Than field__lt=value
__lte Less Than or Equal To field__lte=value
__range Within Range (inclusive) field__range=value1,value2
__startswith Starts With field__startswith=value
__contains Contains field__contains=value
__endswith Ends With field__endswith=value
__isnull Field value is null field__isnull
__isnotnull Field value is not null field__isnotnull

The operators __isnull and __isnotnull do not require any additional value; their presence in the query is sufficient.

Examples

Numeric Fields (e.g., verification_timestamp)

GET https://api.openpublishing.com/resource/v4/sales?verification_timestamp=1719792000
GET https://api.openpublishing.com/resource/v4/sales?verification_timestamp__eq=1719792000
GET https://api.openpublishing.com/resource/v4/sales?verification_timestamp__gt=1719792000
GET https://api.openpublishing.com/resource/v4/sales?verification_timestamp__range=1719792000,1719784900

String Fields (e.g., distribution_channel)

GET https://api.openpublishing.com/resource/v4/sales?distribution_channel=Amazon%20Marketplace
GET https://api.openpublishing.com/resource/v4/sales?distribution_channel__startswith=Amazon
GET https://api.openpublishing.com/resource/v4/sales?distribution_channel__contains=Market
GET https://api.openpublishing.com/resource/v4/sales?ean__isnull

Notes

  1. The syntax is consistent across all parameter types, but some operators may not make logical sense for certain data types (e.g., __contains for numeric values).
  2. The __range operator takes two comma-separated values representing the lower and upper bounds of the range (inclusive).
  3. If not otherwise indicated, string comparisons are case-insensitive, and strings are normalized for comparison (e.g., "ä" is treated as "a").
  4. Multiple query parameters can be combined using the & character to create more complex filters. These filters are combined using a logical AND.

Simple Example of Combined Filters

To find all sales from Amazon Marketplace verified after a specific timestamp:

GET https://api.openpublishing.com/resource/v4/sales?distribution_channel__eq=Amazon%20Marketplace&verification_timestamp__gt=1719792000

This query will return all sales where the distribution channel is exactly "Amazon Marketplace" and the verification timestamp (Current Epoch Unix Timestamp) is greater than 1719792000 (2024-07-01 00:00:00 UTC).

More Complex Example of Combined Filters

GET https://api.openpublishing.com/resource/v4/sales?distribution_channel__startswith=Amazon&period_begin__gte=2024-01-01&booking_type__ne=cancelation&booking_type__ne=fee

This query includes all sales transactions executed across all Amazon channels from 2024 onwards, excluding cancellations and fees.

Null Values

A field that carries no value at all is reported as null in the response. Only the two dedicated operators select on it:

  • field__isnull selects the records in which the field is null
  • field__isnotnull selects the records in which the field has a value

No other operator matches a null field:

  • field__ne=value selects only records in which the field has a value and that value differs from value — records in which the field is null are not returned
  • __eq, __gt, __gte, __lt, __lte, __range, __startswith, __contains and __endswith likewise never match a null field

__ne therefore does not mean "everything except this value". On product prices, for example:

GET https://api.openpublishing.com/resource/v4/products/{product_id}/prices?qualifier_code__ne=08

returns the prices that carry a qualifier code other than 08, and omits the prices that carry no qualifier code. Covering both requires a second request with qualifier_code__isnull.

Sort Order

The sort query parameter determines the order of the items in a collection response. Its value is a field name, optionally followed by an order suffix:

sort=field_name[__asc|__desc]

Where:

  • __asc sorts ascending
  • __desc sorts descending
  • with no suffix, the order is ascending
  • field names and order suffixes are case-insensitive
  • several sort keys may be given as a comma-separated list, applied from left to right, e.g. sort=publication_date__desc,title__asc

Sorting Example

GET https://api.openpublishing.com/resource/v4/products?sort=title__asc

Notes

  1. The suffix form is the only accepted syntax. A leading - to signify descending order is not supported: sort=-title is rejected with 400 Bad Request.
  2. An order suffix other than __asc or __desc is rejected with 400 Bad Request.
  3. Each resource sorts on its own set of fields, and that set is not necessarily the set of fields the resource filters on. A field the resource cannot sort on is rejected with 400 Bad Request.
  4. sort is never rejected as an unrecognised query parameter, but not every resource acts on it: a resource that applies no ordering from it ignores the parameter and returns no error. Unless a resource documents that it honours sort, the order of a collection is not defined and is not guaranteed to stay stable across the pages of a paginated result.

Unknown Query Parameters

The pagination parameters (page, page_size, display), sort, and the authentication parameters are reserved: they are never interpreted as field filters. Every other query parameter is taken to be a filter on a field of the resource.

An unrecognised filter parameter is not ignored:

  • an unrecognised operator suffix — for instance title__containss=Faust — is rejected with 400 Bad Request
  • an unrecognised field name is rejected with 400 Bad Request, and the error names the offending parameter

Pagination

The API supports pagination using the display and page query parameters:

  • display: Number of items to display per page (default: 1000)
  • page: Page number to retrieve (default: 1)

Example

GET https://api.openpublishing.com/resource/v4/products?display=100&page=2
returns page 2 with maximal 100 products.

Response

The JSON response contains pagination related links in the "_links"-object.

_links Object

Field Type Description
first String URL to the first page of results
next String URL to the next page of results (null if N/A)
prev String URL to the previous page of results (null if N/A)
self String URL to the current page of results