Skip to main content
POST
/
latest_headlines
Get latest headlines
curl --request POST \
  --url https://api.newscatcherapi.com/v2/latest_headlines \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
  "when": "12h",
  "lang": "en",
  "not_lang": "en",
  "countries": "<string>",
  "not_countries": "<string>",
  "topic": "business",
  "sources": "nytimes.com,theguardian.com",
  "not_sources": "<string>",
  "ranked_only": true,
  "page_size": 100,
  "page": 1
}'
{
  "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": {
    "lang": [
      "<string>"
    ],
    "not_lang": [
      "<string>"
    ],
    "countries": [
      "<string>"
    ],
    "not_countries": [
      "<string>"
    ],
    "page": 123,
    "size": 123,
    "sources": [
      "<string>"
    ],
    "not_sources": [
      "<string>"
    ],
    "topic": "<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.

Body

application/json
​
when
string
default:7d

The time period for which you want to get the latest headlines. Accepted forms:

  • 7d: Dailly Form (last 7 days time period), 30d (last 30 days time period)
  • 1h: Hourly Form (last hour), 24h (last 24 hours)
Example:

"12h"

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

"en"

​
not_lang
enum<string>

The language you want to search in. 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
Example:

"en"

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

"business"

​
sources
string

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

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

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

Example:

true

​
page_size
integer

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

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

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

1

Response

OK

The response for a successful latest headlines 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[]

A list of articles.

​
user_input
object

The user input for a latest headlines request.