GET
/
search
curl --request GET \
  --url https://api.newscatcherapi.com/v2/search \
  --header 'x-api-key: <api-key>'
{
  "status": "ok",
  "total_hits": 123,
  "page": 123,
  "total_pages": 123,
  "page_size": 123,
  "articles": [
    {
      "title": "<string>",
      "author": "<string>",
      "published_date": "<string>",
      "published_date_precision": "<string>",
      "link": "<string>",
      "clean_url": "<string>",
      "excerpt": "<string>",
      "summary": "<string>",
      "rights": "<string>",
      "rank": 123,
      "topic": "<string>",
      "country": "<string>",
      "language": "<string>",
      "authors": "<string>",
      "is_opinion": true,
      "twitter_account": "<string>",
      "_score": 123,
      "_id": "<string>"
    }
  ],
  "user_input": {
    "q": "Elon Musk",
    "search_in": [
      "<string>"
    ],
    "lang": [
      "<string>"
    ],
    "not_lang": [
      "<string>"
    ],
    "countries": [
      "<string>"
    ],
    "not_countries": [
      "<string>"
    ],
    "from": "<string>",
    "to": "<string>",
    "ranked_only": "<string>",
    "from_rank": 123,
    "to_rank": 123,
    "sort_by": "<string>",
    "page": 123,
    "size": 123,
    "sources": [
      "<string>"
    ],
    "not_sources": [
      "<string>"
    ],
    "topic": "<string>",
    "published_date_precision": "<string>"
  }
}

Authorizations

​
x-api-key
string
header
required

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.

Query Parameters

​
q
string
required

Keyword/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.

Example:

"\"Elon Musk\""

​
lang
enum<string>

Specifies the languages of the search. For example: en. The only accepted format is ISO 639-1 — 2 letter code.

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
Example:

"en"

​
not_lang
enum<string>

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
Example:

"full"

​
from
string

YYYY/mm/dd From which point in time to start the search. The default timezone is UTC. Defaults to the past week.

Example:

"2021/05/06"

​
to
string

YYYY/mm/dd Until which point in time to search for. The default timezone is UTC.

Example:

"2021/05/06"

​
search_in
enum<string>

By default, we search what you specified in the q parameter in both title and summary of the article. However, you can limit this to either title or summary.

Available options:
title,
summary,
title_summary
Example:

"title"

​
countries
string

Countries where the news publisher is located. One or multiple countries can be used in the search. The only acceptable format is ISO 3166-1 alpha-2 For example, US,CA,MX or just US

Important: This parameter is not responsible for the countries mentioned in the news article.

Example:

"US,CA"

​
not_countries
string

The inverse of the countries parameter.

Example:

"US,CA"

​
topic
enum<string>

The topic to which you want to restrict the articles of your choice. Not all news articles are assigned with a topic, therefore, we cannot guarantee that 100% of topics talking about technology will be assigned a tech label.

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

"business"

​
sources
string

One or more news resources to filter your search. It should be the normal form of the URL, For example: nytimes.com,theguardian.com

Example:

"nytimes.com,theguardian.com"

​
not_sources
string

One or more sources to be excluded from the search. Comma-separated list. For example: nytimes.com,cnn.com,wsj.com

Example:

"wsj.com"

​
ranked_only
boolean

Default: True Limit the search only for the sources which are in the top 1 million online websites. Unranked sources are assigned a rank that equals 999999

Example:

true

​
from_rank
integer

[0:999999] The lowest boundary of the rank of a news website to filter by. Important: lower rank means that a source is more popular

Required range: 1 <= x <= 999999
Example:

1000

​
to_rank
integer

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

Required range: 1 <= x <= 999999
Example:

1000

​
sort_by
enum<string>

relevancy (default value) — the most relevant results first date — the most recently published results first rank — the results from the highest-ranked sources first

Available options:
relevancy,
date,
rank
Example:

"rank"

​
page_size
integer

[1:100] How many articles to return per page.

Required range: 1 <= x <= 100
Example:

100

​
page
integer

The number of the page. Use it to scroll through the results. This parameter is used to paginate: scroll through results because one API response cannot return more than 100 articles.

Required range: x >= 1
Example:

1

Response

200
application/json
OK

The response for a successful search request.

​
status
enum<string>

The status of the response.

Available options:
ok,
No matches for your search.
Example:

"ok"

​
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.

The article object.

​
user_input
object

The user input for a search request.

Was this page helpful?

Suggest editsRaise issue
Rate limits and quatasSearch news