Skip to main content
Filters narrow the articles a search ranks. In the JSON body of POST /search list filters are arrays or comma-separated strings; in the query string of GET /search they are comma-separated strings.

​
Time window

​
string
default:"7d"
How far back to search, counted from now: a number and a unit, for example 15m, 2h, 1d, 1w, 15 minutes, 2 hours or 1 day. Units are minutes (m, min, minute, minutes), hours (h, hr, hour, hours), days (d, day, days) and weeks (w, week, weeks). From 1 minute up to your plan’s history (30 days on the free plan). The window applies to the publication date, or to the crawl date with sort_by=crawled_at. A window longer than your history is cut to it, and the response says "clamped": true in window.

​
Languages, countries and publishers

​
string | string[]
Only articles in these languages: ISO 639-1 codes, at most 100, for example ["en", "de"]. zh is searched as cn. If none of them is English, the search runs in the original language instead of the English translation.
​
string | string[]
Leave out articles in these languages: ISO 639-1 codes, at most 100. zh is excluded as cn.
​
string | string[]
Only articles from publishers in these countries: ISO 3166-1 alpha-2 codes, at most 100, for example ["US", "GB"].
​
string | string[]
Leave out articles from publishers in these countries: ISO 3166-1 alpha-2 codes, at most 100.
​
string | string[]
Only these publishers: domains, at most 100, for example ["reuters.com", "bbc.co.uk"]. Matches any copy of an article, and the result then shows the domain you asked for: its name and a link on that domain.
​
string | string[]
Leave out these publishers: domains, at most 100. An article is dropped when any of its copies comes from one of them.

​
Coverage and content type

​
integer
default:"0"
Only stories carried by at least this many newsrooms (0 to 1,000). See Stories.
​
string
default:"news"
news keeps real news articles only. all returns every article, whatever its type.

​
Order and size of the results

​
string
default:"relevancy"
  • relevancy: best match first.
  • published_at: newest publication first.
  • crawled_at: newest crawl first.
A date order sorts the best matches of q (at least 100, or 5 times limit), not every article of the window. With a date order, collapse=diverse keeps every article, as duplicates does. A publication date later than the crawl date counts as the crawl date.
​
integer
default:"20"
Number of articles to return, 1 to 100. Your plan may allow fewer (50 on the free plan); a larger limit gets 403.
​
string
default:"diverse"
What happens to several articles of one story: diverse, story or duplicates. See Stories.
​
string | string[]
Enterprise fields to add to every result. Other plans get 403 with enterprise_field. See Response fields.

​
Example