How to
Search by date & time
Learn how to filter your search results by their publication date and time
While searching for news articles you’ll often need to filter out the results by
their publication date. The articles returned by our News API have their
publication date and time as an attribute :
The
Which would yield articles such as:
Querying with phrases returns a slightly different set of news articles, this is
because our simple phrases aren’t as granular as using specific dates. It’s hard
to precisely look for a complex time period time. For instance, it’s easier to
simply use the date
Also, the phrases are relative to the time of the request. Therefore, if you make
a query using phrases today, and use it to fetch news articles again next week, you’ll
get different results. On the other hand, if you use the dates you’ll get the same
set of news articles.
To work around this limit, it’s recommended to break down your query time
intervals into smaller chunks of time like a month, a fortnight, a week, or even
a day depending on the query. In the case of the previous ‘Apple’ query, you
will need to break it down into individual days to fetch all the results for the
two month time period:
and so on.
The
published_date. Using this
information you can further drill down in your search queries on the
v2/search and
v2/latest_headlines
endpoints.
/search
The /search endpoint has two parameters, to and from, that enable you to
filter your news search results by their publication dates.
Let’s say, you want to understand the general perception of the new Tesla UI
update. To achieve this you’ll need to fetch the articles published around the
time the update was pushed to the cars. If you decide on the date range of
2021/12/01 to 2022/31/01, you would use the to and from parameters to
make a request like*:*
The default timezone for the
to and from parameters is UTC.In our Python SDK, the to and from parameter names are replaced by
to_ and from_ to avoid clashes with Python keywords.
Search using phrases
You can use simple phrases like ‘three months ago’ and ‘6 weeks ago’ instead of specifying the date & time explicitly. For example, ‘Tesla UI’ related news articles can be searched as follows:_2021/07/18_, as opposed to
'7 months and 27 days ago'. And if you want to specify the time, things get
even more complicated.
If you want to learn how to make more detailed queries using date/time
phrases, check out the
dateparser module docs.
Making better queries
The ‘Tesla UI’ search query is very specific so the number of results isn’t that high. But if you were to make a similar search for a broader term like ‘Apple’, you would run into the API result limit of 10,000 articles:Date precision
One thing to keep in mind when searching by date is thepublished_date_precision attribute. There are three types of date precision
defined in our News API:
"full"— day and time of an article is correctly identified with the appropriate timezone"timezone unknown"— day and time of an article is correctly identified without timezone"date"— only the day is identified without an exact time
Distribution of `published_date_precision` attribute
/latest_headlines
The /latest_headlines endpoint doesn’t have the to and from parameters.
Instead, it has the when parameter that dictates the time period starting from
which you want to get the articles for. It accepts two forms:
- Daily Form
Xd7d=> last 7 days time period - Hourly Form
Xh24h=> last 12 hours
12h will yield
more and older results than a request for articles from the last one hour 1h.
The default time period is the amount of historical data available for your
subscription type. For example, for the free no-card
trial, the
latest_headlines endpoint will return the articles from the last two
weeks.