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.
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.
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.
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.
See also
