Retrieve latest headlines

POST

api

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",
  "associated_towns": [
    {
      "name": "New York City, New York",
      "ai_validated": true,
      "description": [
        "CITY_STATE_COUNTY_QUERY",
        "NEAR_CITY_STATE_QUERY"
      ]
    },
    {
      "name": "Los Angeles, California",
      "ai_validated": true,
      "description": [
        "HYPERLOCAL_SOURCES_INCLUDE_QUERY",
        "LOCAL_SOURCES_EXCLUDE_QUERY"
      ]
    }
  ],
  "search_in_ai_associated_town": true,
  "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

associated_towns

object[]

required

An array of town entities related to the articles. Each town entity contains information about a specific town and the association methods to be used for searching.

To learn more, see Town association methods.

associated_towns.name

string

required

The full name of the town, including the state. Format must be "City, State". For example, "San Francisco, California".

Example:

"San Francisco, California"

associated_towns.ai_validated

boolean

default:true

Indicates whether the town name was validated by AI.

Example:

true

associated_towns.description

enum<string>[]

An array of strings specifying the association methods used for this town. These methods determine how the API searches for articles related to this town.

Available association methods:

HYPERLOCAL_SOURCES_EXCLUDE_QUERY: Searches hyperlocal sources, excluding state names and IDs.
HYPERLOCAL_SOURCES_INCLUDE_QUERY: Performs an exact match of the city name in the title or content.
LOCAL_SOURCES_EXCLUDE_QUERY: Searches local sources, excluding state names and IDs.
CITY_STATE_COUNTY_QUERY: Conducts a global search using city, state, and county combinations.
NEAR_CITY_STATE_QUERY: Performs a proximity search, finding city and state within 15 words of each other.

To learn more, see Town association methods.

Available options:

HYPERLOCAL_SOURCES_EXCLUDE_QUERY,

HYPERLOCAL_SOURCES_INCLUDE_QUERY,

LOCAL_SOURCES_EXCLUDE_QUERY,

CITY_STATE_COUNTY_QUERY,

NEAR_CITY_STATE_QUERY

Example:

["HYPERLOCAL_SOURCES_INCLUDE_QUERY"]

Example:

[
  {
    "name": "New York City, New York",
    "ai_validated": true,
    "description": [
      "CITY_STATE_COUNTY_QUERY",
      "NEAR_CITY_STATE_QUERY"
    ]
  },
  {
    "name": "Los Angeles, California",
    "ai_validated": true,
    "description": [
      "HYPERLOCAL_SOURCES_INCLUDE_QUERY",
      "LOCAL_SOURCES_EXCLUDE_QUERY"
    ]
  }
]

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"

search_in_ai_associated_town

boolean

default:false

Determines whether to include AI-extracted town names in the search. If true, the API searches for articles mentioning AI-extracted towns and towns specified in the associated_towns parameter.

Note: The search_in_ai_associated_town parameter is only available for the v3_local_news_ai_extraction_nlp plan. Data for AI-associated towns is only available from September 24, 2024, onwards.

Example:

true

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

200

application/json

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.

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

object[]

A list of articles matching the search criteria.

The data model representing a single article in the search results. Required fields are always non-null. Optional fields may be null/undefined if data extraction is unsuccessful.

articles.id

string

required

The unique identifier for the article.

articles.title

string

required

The title of the article.

articles.link

string

required

The URL link to the article.

articles.content

string

required

A snippet or summary of the article's content.

articles.published_date

string

required

The date and time the article was published.

articles.published_date_precision

string

required

The precision of the published date.

articles.is_opinion

boolean

required

Indicates if the article is an opinion piece.

articles.domain_url

string

required

The domain URL of the article's source.

articles.rank

integer

required

The rank of the article's source.

articles.associated_town

object[]

A list of towns associated with the article.

Represents a town associated with an article.

articles.ai_associated_town

object[] | null

A list of towns associated with the article, as identified by AI analysis. Can be null.

articles.score

number

The relevance score of the article.

articles.author

string

The primary author of the article.

articles.description

string

A brief description of the article.

articles.media

string

The URL of the media associated with the article, typically an image.

articles.authors

string[]

A list of authors of the article.

articles.updated_date

string

The date and time the article was last updated.

articles.updated_date_precision

string

The precision of the updated date.

articles.twitter_account

string | null

The Twitter account associated with the article. Can be null.

articles.parent_url

string

The parent URL of the article, typically representing the homepage of the source.

articles.word_count

integer

The word count of the article.

articles.country

string

The country code where the article was published.

articles.rights

string

The rights information for the article, typically the domain name.

articles.language

string

The language code in which the article is written.

articles.nlp

object

Natural Language Processing data for the article.

articles.paid_content

boolean

Indicates if the article is paid content.

user_input

object

The user input parameters for the search.

Was this page helpful?

Suggest edits Raise issue

Search articles Retrieve sources

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",
  "associated_towns": [
    {
      "name": "New York City, New York",
      "ai_validated": true,
      "description": [
        "CITY_STATE_COUNTY_QUERY",
        "NEAR_CITY_STATE_QUERY"
      ]
    },
    {
      "name": "Los Angeles, California",
      "ai_validated": true,
      "description": [
        "HYPERLOCAL_SOURCES_INCLUDE_QUERY",
        "LOCAL_SOURCES_EXCLUDE_QUERY"
      ]
    }
  ],
  "search_in_ai_associated_town": true,
  "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": {}
}

Overview

Endpoints

Retrieve latest headlines

Authorizations

Body

Response