> ## Documentation Index
> Fetch the complete documentation index at: /docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Filters and sorting

> Narrow a search by time window, language, country, publisher, coverage and content type, and choose the order of the results.

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

**search\_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

**languages** `string | string[]`

Only articles in these languages:
[ISO 639-1 codes](https://en.wikipedia.org/wiki/ISO_639-1),
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.

**not\_languages** `string | string[]`

Leave out articles in these languages: ISO 639-1 codes, at most 100. `zh` is
excluded as `cn`.

**countries** `string | string[]`

Only articles from publishers in these countries:
[ISO 3166-1 alpha-2 codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2),
at most 100, for example `["US", "GB"]`.

**not\_countries** `string | string[]`

Leave out articles from publishers in these countries: ISO 3166-1 alpha-2
codes, at most 100.

**sources** `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.

**not\_sources** `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

**min\_newsrooms** `integer` (default: 0)

Only stories carried by at least this many newsrooms (0 to 1,000). See
[Stories](/docs/news/stories.md).

**content\_type** `string` (default: news)

`news` keeps real news articles only. `all` returns every article, whatever
its type.

## Order and size of the results

**sort\_by** `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.

**limit** `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`.

**collapse** `string` (default: diverse)

What happens to several articles of one story: `diverse`, `story` or
`duplicates`. See [Stories](/docs/news/stories.md#repeated-articles-of-one-story).

**include** `string | string[]`

Enterprise fields to add to every result. Other plans get `403` with
`enterprise_field`. See [Response fields](/docs/news/response-fields.md#enterprise-fields).

## Example

```bash theme={null}
curl -X POST "https://api.newscatcherapi.com/news-api/search" \
  -H "x-api-key: $NEWSCATCHER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "q": "port strike",
    "search_window": "3d",
    "countries": ["US", "CA"],
    "not_sources": ["example-aggregator.com"],
    "min_newsrooms": 3,
    "collapse": "story",
    "sort_by": "published_at",
    "limit": 50
  }'
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.