Skip to main content
POST
/
api
/
latest_headlines
Retrieve latest headlines
curl --request POST \
  --url https://local-news.newscatcherapi.com/api/latest_headlines \
  --header 'Content-Type: application/json' \
  --header 'x-api-token: <api-key>' \
  --data '
{
  "when": "7d",
  "locations": [
    "New York City, New York",
    "Los Angeles, California"
  ],
  "detection_methods": [
    "dedicated_source",
    "proximity_mention",
    "ai_extracted"
  ],
  "lang": [
    "en",
    "es"
  ],
  "countries": [
    "US",
    "CA"
  ],
  "sources": [
    "nytimes.com",
    "theguardian.com"
  ],
  "not_sources": [
    "cnn.com",
    "wsj.com"
  ],
  "parent_url": [
    "wsj.com/politics",
    "wsj.com/tech"
  ],
  "is_paid_content": false,
  "page": 2,
  "page_size": 100,
  "word_count_min": 300,
  "word_count_max": 1000,
  "clustering": true,
  "theme": [
    "Business",
    "Finance"
  ],
  "PER_entity_name": "\"Elon Musk\" OR \"Jeff Bezos\"",
  "LOC_entity_name": "\"San Francisco\" OR \"New York City\"",
  "MISC_entity_name": "AWS OR \"Microsoft Azure\"",
  "ORG_entity_name": "\"Apple Inc\" OR Microsoft",
  "title_sentiment_min": -0.5,
  "title_sentiment_max": 0.5,
  "content_sentiment_min": -0.5,
  "content_sentiment_max": 0.5,
  "include_translation_fields": true
}
'
{
  "status": "ok",
  "total_hits": 123,
  "page": 123,
  "total_pages": 123,
  "page_size": 123,
  "articles": [],
  "user_input": {}
}

Authorizations

​
x-api-token
string
header
required

API Key to authenticate requests.

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

Body

application/json

Common parameters shared across standard endpoints.

​
when
string
default:7d

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

Format examples:

  • 7d: Last seven days
  • 30d: Last 30 days
  • 1h: Last hour
  • 24h: Last 24 hours
Example:

"7d"

​
locations
string[]

The location(s) to search for in articles. Format should be "City, State". Example: ["San Francisco, California"]

Example:
[
  "New York City, New York",
  "Los Angeles, California"
]
​
detection_methods
enum<string>[]

The location detection methods to filter results by:

  • dedicated_source: Identifies locations based on sources exclusively covering a specific location.
  • local_section: Identifies locations through location-specific sections within larger publications.
  • regional_source: Identifies locations using regional context from state-level publications.
  • standard_format: Identifies locations written in standard formats like "City, State" or "City, County".
  • proximity_mention: Identifies cities and states mentioned within 15 words of each other.
  • ai_extracted: Identifies locations through AI-based content analysis. Requires AI Extraction plan.

For detailed information, see Location detection methods.

Available options:
dedicated_source,
local_section,
regional_source,
standard_format,
proximity_mention,
ai_extracted
Example:
[
  "dedicated_source",
  "proximity_mention",
  "ai_extracted"
]
​
lang

The language(s) of the search. The only accepted format is the two-letter ISO 639-1 code. To select multiple languages, use a comma-separated string or an array of strings.

To learn more, see Enumerated parameters > Language.

Example:
["en", "es"]
​
countries

The countries where the news publisher is located. The accepted format is the two-letter ISO 3166-1 alpha-2 code. To select multiple countries, use a comma-separated string or an array of strings.

To learn more, see Enumerated parameters > Country.

Example:
["US", "CA"]
​
sources

One or more news sources to narrow down the search. The format must be a domain URL. Subdomains, such as finance.yahoo.com, are also acceptable. To specify multiple sources, use a comma-separated string or an array of strings.

Example:
["nytimes.com", "theguardian.com"]
​
not_sources

The news sources to exclude from the search. To exclude multiple sources, use a comma-separated string or an array of strings.

Example:
["cnn.com", "wsj.com"]
​
parent_url

The categorical URL(s) to filter your search. To filter your search by multiple categorical URLs, use a comma-separated string or an array of strings.

Example:
["wsj.com/politics", "wsj.com/tech"]
​
is_paid_content
boolean

If false, returns only articles that have publicly available complete content. Some publishers partially block content, so this setting ensures that only full articles are retrieved.

Example:

false

​
page
integer
default:1

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

Required range: x >= 1
Example:

2

​
page_size
integer
default:100

The number of articles to return per page. Range: 1 to 1000.

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

100

​
word_count_min
integer

The minimum number of words an article must contain. To be used for avoiding articles with small content.

Required range: x >= 0
Example:

300

​
word_count_max
integer

The maximum number of words an article can contain. To be used for avoiding articles with large content.

Required range: x >= 0
Example:

1000

​
clustering
boolean
default:false

If true, groups similar articles into clusters and returns clustered results. If false, returns individual articles without clustering.

To learn more, see Clustering news articles.

Example:

true

​
theme

Filters articles based on their general topic, as determined by NLP analysis. To select multiple themes, use a comma-separated string or an array of strings.

To learn more, see NLP features.

Available options: Business, Economics, Entertainment, Finance, Health, Politics, Science, Sports, Tech, Crime, Financial Crime, Lifestyle, Automotive, Travel, Weather, General.

Example:
["Business", "Finance"]
​
PER_entity_name
string

Filters articles that mention specific person names, as identified by NLP analysis.

  • To specify multiple names, use AND, OR, NOT operators, and \" escape literals for exact matches.
  • To search in translations, combine with the translation options of the search_in parameter (e.g., title_content_translated).

To learn more, see Search by entity.

Example:

"\"Elon Musk\" OR \"Jeff Bezos\""

​
LOC_entity_name
string

Filters articles that mention specific location names, as identified by NLP analysis.

  • To specify multiple locations, use AND, OR, NOT operators, and \" escape literals for exact matches.
  • To search in translations, combine with the translation options of the search_in parameter (e.g., title_content_translated).

To learn more, see Search by entity.

Example:

"\"San Francisco\" OR \"New York City\""

​
MISC_entity_name
string

Filters articles that mention other named entities not falling under person, organization, or location categories. Includes events, nationalities, products, works of art, and more.

  • To specify multiple entities, use AND, OR, NOT operators, and \" escape literals for exact matches.
  • To search in translations, combine with the translation options of the search_in parameter (e.g., title_content_translated).

To learn more, see Search by entity.

Example:

"AWS OR \"Microsoft Azure\""

​
ORG_entity_name
string

Filters articles that mention specific organization names, as identified by NLP analysis.

  • To specify multiple organizations, use AND, OR, NOT operators, and \" escape literals for exact matches.
  • To search in translations, combine with the translation options of the search_in parameter (e.g., title_content_translated).

To learn more, see Search by entity.

Example:

"\"Apple Inc\" OR Microsoft"

​
title_sentiment_min
number<float>

Filters articles based on the minimum sentiment score of their titles.

Range is -1.0 to 1.0, where:

  • Negative values indicate negative sentiment.
  • Positive values indicate positive sentiment.
  • Values close to 0 indicate neutral sentiment.

To learn more, see NLP features.

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

-0.5

​
title_sentiment_max
number<float>

Filters articles based on the maximum sentiment score of their titles.

Range is -1.0 to 1.0, where:

  • Negative values indicate negative sentiment.
  • Positive values indicate positive sentiment.
  • Values close to 0 indicate neutral sentiment.

To learn more, see NLP features.

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

0.5

​
content_sentiment_min
number<float>

Filters articles based on the minimum sentiment score of their content.

Range is -1.0 to 1.0, where:

  • Negative values indicate negative sentiment.
  • Positive values indicate positive sentiment.
  • Values close to 0 indicate neutral sentiment.

To learn more, see NLP features.

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

-0.5

​
content_sentiment_max
number<float>

Filters articles based on the maximum sentiment score of their content.

Range is -1.0 to 1.0, where:

  • Negative values indicate negative sentiment.
  • Positive values indicate positive sentiment.
  • Values close to 0 indicate neutral sentiment.

To learn more, see NLP features.

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

0.5

​
include_translation_fields
boolean
default:false

If true, includes English translation fields in the response (title_translated_en, content_translated_en, and NLP translation fields). If false, excludes translation fields.

Example:

true

Response

A successful response containing the latest headlines since the specified time. The response may include clustering information if enabled.

  • Latest Headlines Response
  • Clustered Latest Headlines Response

The response model for the Latest headlines request.

​
status
string
default:ok
required

The status of the response.

​
total_hits
integer
required

The total number of articles matching the search criteria.

​
page
integer
required

The current page number of the results.

​
total_pages
integer
required

The total number of pages available for the given search criteria.

​
page_size
integer
required

The number of articles per page.

​
articles
Article Result · object[]

A list of articles matching the search criteria.

​
user_input
User Input · object

The user input parameters for the search.