Version 2 API: filtering

Query structure

Data returned by the API can be filtered in the same way as stories returned in the web site search.

All the filters (search terms) available to a web site user are also available to an API consumer. In addition, the uri representing a web site search can be reused as an API search with minimal change.

For example, the uri for a search for stories tagged with "diabetes" is:

If you are using HTTP header authentication, then the uri for an API call to access the same set of stories is:

If you require a complex search, you can create it first using the web site search, and then reuse it in an API call.

Available uri query parameters

There is a wide range of filtering parameteres (search terms) available. Many of them are documented in our help pages for search.

Please note that all incoming/outgoing datetime values will be in UTC.

Help with searching

Additional search terms

Help with service selection

Phrase searching

Response searching

Skip and take

For most collections, we return a small number of items in a fixed order. For example, we return tags in alphabetic order.

You can skip the first S items in a collection by adding skip=S to your request.

You can ask for the next T items by adding take=T to your request.

In all collections, there is a default and a maximum accepted T.

Recently read