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, learn Advanced querying in News API v2.

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[]

An array of articles matching the search criteria.

user_input
object

The user input for a search request.

Was this page helpful?

Search newsGet latest headlines