Filter by date

News API gives you five parameters for date-based filtering. By default, all date filters apply to the article’s publication date. To filter by the date NewsCatcher indexed the article instead, set by_parse_date=true.

Set a date range

Use from_ and to_ to retrieve articles published within a specific window. Both parameters accept ISO 8601 dates, plain English expressions like 7 days ago, and duration shorthands like 30d or 24h.

curl -X POST "https://v3-api.newscatcherapi.com/api/search" \
  -H "x-api-token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "q": "climate change",
    "from_": "7d",
    "to_": "now"
  }'

from newscatcher import NewscatcherApi

client = NewscatcherApi(api_key="YOUR_API_KEY")
response = client.search.post(
    q="climate change",
    from_="7d",
    to_="now"
)

import { NewscatcherApiClient } from "newscatcher-sdk";

const client = new NewscatcherApiClient({ apiKey: "YOUR_API_KEY" });
const response = await client.search.post({
  q: "climate change",
  from_: "7d",
  to_: "now"
});

NewscatcherApiClient client = NewscatcherApiClient.builder()
    .apiKey("YOUR_API_KEY")
    .build();
PostSearchResponse response = client.search().post(
    PostSearchRequest.builder()
        .q("climate change")
        .from_("7d")
        .to_("now")
        .build()
);

Filter by recency

Use when with /latest_headlines to retrieve articles published within a rolling time window — for example, the last 24 hours or the last 7 days.

when is exclusive to /latest_headlines. The search endpoints use from_/to_ instead — the two approaches are not interchangeable.

curl "https://v3-api.newscatcherapi.com/api/latest_headlines?when=24h&lang=en" \
  -H "x-api-token: YOUR_API_KEY"

from newscatcher import NewscatcherApi

client = NewscatcherApi(api_key="YOUR_API_KEY")
response = client.latest_headlines.get(
    when="24h"
)

import { NewscatcherApiClient } from "newscatcher-sdk";

const client = new NewscatcherApiClient({ apiKey: "YOUR_API_KEY" });
const response = await client.latestHeadlines.get({
  when: "24h"
});

NewscatcherApiClient client = NewscatcherApiClient.builder()
    .apiKey("YOUR_API_KEY")
    .build();
GetLatestHeadlinesResponse response = client.latestHeadlines().get(
    GetLatestHeadlinesRequest.builder()
        .when("24h")
        .build()
);

Use parse date

Use by_parse_date=true when you need to filter by the date NewsCatcher indexed the article rather than its publication date. This is useful when you need to:

Track articles ingested in a specific time window regardless of when they were published.
Build incremental pipelines by storing the parse_date of the most recent article from each request and using it as from_ in the next request, avoiding gaps or overlaps.

curl -X POST "https://v3-api.newscatcherapi.com/api/search" \
  -H "x-api-token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "q": "electric vehicles",
    "from_": "7d",
    "to_": "now",
    "by_parse_date": true
  }'

from newscatcher import NewscatcherApi

client = NewscatcherApi(api_key="YOUR_API_KEY")
response = client.search.post(
    q="electric vehicles",
    from_="7d",
    to_="now",
    by_parse_date=True,
)

import { NewscatcherApiClient } from "newscatcher-sdk";

const client = new NewscatcherApiClient({ apiKey: "YOUR_API_KEY" });
const response = await client.search.post({
  q: "electric vehicles",
  from_: "7d",
  to_: "now",
  byParseDate: true,
});

NewscatcherApiClient client = NewscatcherApiClient.builder()
    .apiKey("YOUR_API_KEY")
    .build();
PostSearchResponse response = client.search().post(
    PostSearchRequest.builder()
        .q("electric vehicles")
        .from_("7d")
        .to_("now")
        .byParseDate(true)
        .build()
);

Filter by date precision

The published_date_precision parameter filters articles by the precision of their publication dates. Accepted values:

full: Use when an exact timestamp with a timezone is required, such as for timeline analysis or time-series aggregation.
timezone unknown: Use when time-of-day precision is sufficient and timezone-aware comparison isn’t needed.
date: Use when only the publication day matters and the exact time is not required.

curl -X POST "https://v3-api.newscatcherapi.com/api/search" \
  -H "x-api-token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "q": "earnings report",
    "from_": "2024-01-01",
    "to_": "2024-03-31",
    "published_date_precision": "full"
  }'

from newscatcher import NewscatcherApi

client = NewscatcherApi(api_key="YOUR_API_KEY")
response = client.search.post(
    q="earnings report",
    from_="2024-01-01",
    to_="2024-03-31",
    published_date_precision="full",
)

import { NewscatcherApiClient } from "newscatcher-sdk";

const client = new NewscatcherApiClient({ apiKey: "YOUR_API_KEY" });
const response = await client.search.post({
  q: "earnings report",
  from_: "2024-01-01",
  to_: "2024-03-31",
  publishedDatePrecision: "full",
});

NewscatcherApiClient client = NewscatcherApiClient.builder()
    .apiKey("YOUR_API_KEY")
    .build();
PostSearchResponse response = client.search().post(
    PostSearchRequest.builder()
        .q("earnings report")
        .from_("2024-01-01")
        .to_("2024-03-31")
        .publishedDatePrecision("full")
        .build()
);

Get started

Guides and concepts

How to

Troubleshooting

API Reference

Integrations

Libraries

Set a date range

Filter by recency

Use parse date

Filter by date precision

See also

​Set a date range

​Filter by recency

​Use parse date

​Filter by date precision

​See also

Set a date range

Filter by recency

Use parse date

Filter by date precision

See also