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.

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