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"
  ],
  "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",
    "Jeff Bezos"
  ],
  "LOC_entity_name": [
    "California",
    "New York"
  ],
  "MISC_entity_name": [
    "Bitcoin",
    "Blockchain"
  ],
  "ORG_entity_name": [
    "Apple",
    "Microsoft"
  ],
  "title_sentiment_min": -0.5,
  "title_sentiment_max": 0.5,
  "content_sentiment_min": -0.5,
  "content_sentiment_max": 0.5
}'
{
  "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
​
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.

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.

Examples:

  • "en,es"
  • ["en", "es"]

To learn more, see Enumerated parameters > Language.

Example:
["en", "es"]
​
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.

Examples:

  • "nytimes.com, theguardian.com"
  • ["nytimes.com", "theguardian.com"]
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.

Examples:

  • "cnn.com, wsj.com"
  • ["cnn.com", "wsj.com"]
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.

Examples:

  • "wsj.com/politics,wsj.com/tech"
  • ["wsj.com/politics", "wsj.com/tech"]
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

Determines whether to group similar articles into clusters. If true, the API returns clustered results.

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.

Examples:

  • "Finance, Tech"
  • ["Finance", "Tech"]

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

Filters articles that mention specific person names, as identified by NLP analysis. To specify multiple names, use a comma-separated string or an array of strings.

Examples:

  • "Elon Musk, Jeff Bezos"
  • ["Elon Musk", "Jeff Bezos"]

To learn more, see Search by entity.

Example:
["Elon Musk", "Jeff Bezos"]
​
LOC_entity_name

Filters articles that mention specific location names, as identified by NLP analysis. To specify multiple locations, use a comma-separated string or an array of strings.

Examples:

  • "California, New York"
  • ["California", "New York"]

To learn more, see Search by entity.

Example:
["California", "New York"]
​
MISC_entity_name

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 a comma-separated string or an array of strings.

Examples:

  • "Bitcoin, Blockchain"
  • ["Bitcoin", "Blockchain"]

To learn more, see Search by entity.

Example:
["Bitcoin", "Blockchain"]
​
ORG_entity_name

Filters articles that mention specific organization names, as identified by NLP analysis. To specify multiple organizations, use a comma-separated string or an array of strings.

Examples:

  • "Apple, Microsoft"
  • ["Apple", "Microsoft"]

To learn more, see Search by entity.

Example:
["Apple", "Microsoft"]
​
title_sentiment_min
number

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

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

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

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

Response

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

The response model for the Latest headlines request.

The response model for the Search, Latest headlines, and Search by requests, including search results and metadata.

Response field behavior:

  • Required fields are guaranteed to be present and non-null.
  • Optional fields may be null/undefined if the data couldn't be extracted during processing.
  • To access article properties in the articles response array, use array index notation. For example, articles[n].title, where n is the zero-based index of the article object (0, 1, 2, etc.).

The base response model containing common fields for search operations.

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

The user input parameters for the search.