POST
/
search

Authorizations

x-api-key
string
headerrequired

API Key to authenticate requests.

To access the API, include your API key in the x-api-key header. To obtain your API key, complete the form or contact us directly.

Body

application/json
q
string

The keyword or keywords you're searching for. This is the most important part of your query. For for more examples and explanations, leant Advanced Query Parameter.

lang
enum<string>

The language you want to search in.

Available options:
af,
ar,
bg,
bn,
ca,
cn,
cs,
cy,
da,
de,
el,
en,
es,
et,
fa,
fi,
fr,
gu,
he,
hi,
hr,
hu,
id,
it,
ja,
kn,
ko,
lt,
lv,
mk,
ml,
mr,
ne,
nl,
no,
pa,
pl,
pt,
ro,
ru,
sk,
sl,
so,
sq,
sv,
sw,
ta,
te,
th,
tl,
tr,
tw,
uk,
ur,
vi
not_lang
enum<string>

The language to exclude from the search results. Inverse to the lang parameter.

Available options:
af,
ar,
bg,
bn,
ca,
cn,
cs,
cy,
da,
de,
el,
en,
es,
et,
fa,
fi,
fr,
gu,
he,
hi,
hr,
hu,
id,
it,
ja,
kn,
ko,
lt,
lv,
mk,
ml,
mr,
ne,
nl,
no,
pa,
pl,
pt,
ro,
ru,
sk,
sl,
so,
sq,
sv,
sw,
ta,
te,
th,
tl,
tr,
tw,
uk,
ur,
vi
published_date_precision
enum<string>

The precision of the published date. There are three types:

  • full: The day and time of an article is correctly identified with the appropriate timezone.
  • timezone unknown: The day and time of an article is correctly identified without timezone.
  • date: Only the day is identified without an exact time.
Available options:
full,
timezone unknown,
date
from
string

The start date for the search in YYYY/mm/dd format. The default timezone is UTC. Defaults to the past week.

to
string

The end date for the search in YYYY/mm/dd format. The default timezone is UTC.

search_in
enum<string>

The fields to search for the keywords in.

Available options:
title,
summary,
title_summary
countries
string

The countries where the news publisher is located, using the ISO 3166-1 alpha-2 format. Multiple countries can be specified, separated by commas.

not_countries
string

The countries to exclude from the search results, using the ISO 3166-1 alpha-2 format. Multiple countries can be specified, separated by commas.

topic
enum<string>

The topic to restrict the articles to.

Available options:
news,
sport,
tech,
world,
finance,
politics,
business,
economics,
entertainment,
beauty,
travel,
music,
food,
science,
gaming
sources
string

The news sources to filter the search, specified in the normal form of the URL. For example, nytimes.com,theguardian.com.

not_sources
string

The news sources to exclude from the search, specified as a comma-separated list. For example, nytimes.com,cnn.com,wsj.com.

ranked_only
boolean
default: true

If true, limits the search to sources in the top 1 million online websites. Unranked sources are assigned a rank of 999999.

from_rank
integer

The lowest boundary of the rank of a news website to filter by. Lower rank means a more popular source. Range: [0:999999].

Required range: 0 < x < 999999
to_rank
integer

The upper boundary of the rank of a news website to filter by. Range: [0:999999].

Required range: 0 < x < 999999
sort_by
enum<string>
default: relevancy

The sorting order of the search results.

Available options:
relevancy,
date,
rank
page_size
integer

The number of articles to return per page. Range: [1:100].

Required range: 1 < x < 100
page
integer

The page number for paginated results. Use it to scroll through the results, as one API response cannot return more than 100 articles.

Required range: x > 1

Response

200 - application/json

The response for a successful search request.

status
enum<string>

The status of the response.

Available options:
ok,
No matches for your search.
total_hits
integer

The total number of hits for the search.

page
integer

The current page number.

total_pages
integer

The total number of pages.

page_size
integer

The number of results per page.

articles
object[]

The list of articles returned by the search.

user_input
object

The user input for the search request.

Was this page helpful?

Search newsGet latest headlines