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.

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.