Newscatcher BreakingNews API
Operations to retrieve breaking news articles.
OpenAPI Specification
openapi: 3.0.3
info:
title: Local News AggregationCount BreakingNews API
description: 'The Local News API provides access to local news articles with location-specific filtering capabilities.
## Standard endpoints
- `/search`: Search articles by keywords with simple location filtering ("City, State" format).
- `/latest_headlines`: Retrieve recent articles for specified locations and time periods.
- `/search_by`: Retrieve articles by URL, ID, or RSS GUID.
- `/sources`: List available news sources.
## Advanced endpoints
- `/search/advanced`: Search with structured GeoNames filtering.
- `/latest_headlines/advanced`: Latest headlines with structured GeoNames filtering.
## Features
- Multiple location detection methods including dedicated sources, proximity analysis, and AI extraction
- Natural language processing for sentiment analysis and entity recognition on original content and English translations
- Article clustering for topic analysis
- English translations for non-English content
'
termsOfService: https://newscatcherapi.com/terms-of-service
contact:
name: Maksym Sugonyaka
email: maksym@newscatcherapi.com
url: https://www.newscatcherapi.com/book-a-demo
version: 1.2.0
servers:
- url: https://local-news.newscatcherapi.com
description: Local News API production server
security:
- ApiKeyAuth: []
tags:
- name: BreakingNews
description: Operations to retrieve breaking news articles.
externalDocs:
description: Retrieve breaking news articles.
url: https://www.newscatcherapi.com/docs/news-api/api-reference/breaking-news/breaking-news-get
paths:
/api/breaking_news:
get:
x-fern-sdk-group-name: breaking_news
x-fern-sdk-method-name: get
tags:
- BreakingNews
summary: Get breaking news
description: Retrieves breaking news articles and sorts them based on specified criteria.
operationId: breakingNewsGet
parameters:
- $ref: '#/components/parameters/SortBy'
- $ref: '#/components/parameters/RankedOnly'
- $ref: '#/components/parameters/FromRank'
- $ref: '#/components/parameters/ToRank'
- $ref: '#/components/parameters/Page'
- $ref: '#/components/parameters/PageSize'
- $ref: '#/components/parameters/TopNArticles'
- $ref: '#/components/parameters/IncludeTranslationFields'
- $ref: '#/components/parameters/IncludeNlpData'
- $ref: '#/components/parameters/HasNlp'
- $ref: '#/components/parameters/Theme'
- $ref: '#/components/parameters/NotTheme'
- $ref: '#/components/parameters/OrgEntityName'
- $ref: '#/components/parameters/PerEntityName'
- $ref: '#/components/parameters/LocEntityName'
- $ref: '#/components/parameters/MiscEntityName'
- $ref: '#/components/parameters/TitleSentimentMin'
- $ref: '#/components/parameters/TitleSentimentMax'
- $ref: '#/components/parameters/ContentSentimentMin'
- $ref: '#/components/parameters/ContentSentimentMax'
responses:
'200':
$ref: '#/components/responses/BreakingNewsResponse'
'400':
$ref: '#/components/responses/BadRequestError'
'401':
$ref: '#/components/responses/UnauthorizedError'
'403':
$ref: '#/components/responses/ForbiddenError'
'408':
$ref: '#/components/responses/RequestTimeoutError'
'422':
$ref: '#/components/responses/ValidationError'
'429':
$ref: '#/components/responses/RateLimitError'
'500':
$ref: '#/components/responses/InternalServerError'
post:
x-fern-sdk-group-name: breaking_news
x-fern-sdk-method-name: post
tags:
- BreakingNews
summary: Get breaking news
description: Retrieves breaking news articles and sorts them based on specified criteria.
operationId: breakingNewsPost
requestBody:
$ref: '#/components/requestBodies/BreakingNewsRequestBody'
responses:
'200':
$ref: '#/components/responses/BreakingNewsResponse'
'400':
$ref: '#/components/responses/BadRequestError'
'401':
$ref: '#/components/responses/UnauthorizedError'
'403':
$ref: '#/components/responses/ForbiddenError'
'408':
$ref: '#/components/responses/RequestTimeoutError'
'422':
$ref: '#/components/responses/ValidationError'
'429':
$ref: '#/components/responses/RateLimitError'
'500':
$ref: '#/components/responses/InternalServerError'
components:
schemas:
TopNArticles:
type: integer
minimum: 1
maximum: 100
default: 1
description: "Controls the number of top articles to include for each breaking news event.\n\n**Important limitations**: \n- Maximum value is 100.\n- The product of `top_n_articles` x `page_size` must not exceed 1,000 (total articles limit).\n"
example: 5
RankedOnly:
type: boolean
default: true
description: 'If true, limits the search to sources ranked in the top 1 million online websites. If false, includes unranked sources which are assigned a rank of 999999.
'
example: true
ToRank:
type: integer
minimum: 1
maximum: 999999
default: 999999
format: int32
description: 'The highest boundary of the rank of a news website to filter by. A lower rank indicates a more popular source.
'
example: 100
UserInputDto:
type: object
description: The user input parameters for the request.
additionalProperties: true
LocEntityName:
type: string
description: "Filters articles that mention specific location names, as identified by NLP analysis.\n\n- To specify multiple locations, use `AND`, `OR`, `NOT` operators, and `\\\"` escape literals for exact matches. \n- To search in translations, combine with the translation options of the `search_in` parameter (e.g., `title_content_translated`).\n\nTo learn more, see [Search by entity](https://www.newscatcherapi.com/docs/news-api/how-to/search-by-entity).\n"
example: '"San Francisco" OR "New York City"'
FromRank:
type: integer
minimum: 1
maximum: 999999
default: 1
format: int32
description: 'The lowest boundary of the rank of a news website to filter by. A lower rank indicates a more popular source.
'
example: 100
NlpDataEntity:
type: object
default: {}
description: Natural Language Processing data for the article.
properties:
translation_summary:
type: string
description: 'A brief AI-generated summary of the article''s English translation.
'
theme:
type: string
description: The themes or categories identified in the article.
summary:
type: string
description: A brief AI-generated summary of the article content.
sentiment:
$ref: '#/components/schemas/SentimentScores'
new_embedding:
type: array
items:
type: number
format: float
description: 'A dense 1024-dimensional vector representation of the article content, generated using the [multilingual-e5-large](https://huggingface.co/intfloat/multilingual-e5-large) model. Available for articles indexed before January 1, 2026.
**Note**: The `new_embedding` field is only available in the `v3_nlp_embeddings` subscription plan.
'
qwen_embedding:
type: array
items:
type: number
format: float
description: 'A dense 1024-dimensional vector representation of the article content, generated using the [Qwen3-Embedding-0.6B](https://huggingface.co/Qwen/Qwen3-Embedding) model. Available for articles indexed from January 1, 2026 onward. Embeddings are computed from a combination of the article `title` and `content` fields.
**Note**: The `qwen_embedding` field is only available in the `v3_nlp_embeddings` subscription plan.
'
ner_PER:
allOf:
- $ref: '#/components/schemas/NamedEntityList'
description: Named Entity Recognition for person entities (individuals' names).
ner_ORG:
allOf:
- $ref: '#/components/schemas/NamedEntityList'
description: Named Entity Recognition for organization entities (company names, institutions).
ner_MISC:
allOf:
- $ref: '#/components/schemas/NamedEntityList'
description: Named Entity Recognition for miscellaneous entities (events, nationalities, products).
ner_LOC:
allOf:
- $ref: '#/components/schemas/NamedEntityList'
description: Named Entity Recognition for location entities (cities, countries, geographic features).
translation_ner_PER:
allOf:
- $ref: '#/components/schemas/NamedEntityList'
description: 'Named Entity Recognition for person entities (individuals'' names) extracted from the English translation of the article.
'
translation_ner_ORG:
allOf:
- $ref: '#/components/schemas/NamedEntityList'
description: 'Named Entity Recognition for organization entities (company names, institutions) extracted from the English translation of the article.
'
translation_ner_MISC:
allOf:
- $ref: '#/components/schemas/NamedEntityList'
description: 'Named Entity Recognition for miscellaneous entities (events, nationalities, products) extracted from the English translation of the article.
'
translation_ner_LOC:
allOf:
- $ref: '#/components/schemas/NamedEntityList'
description: 'Named Entity Recognition for location entities (cities, countries, geographic features) extracted from the English translation of the article.
'
iptc_tags_name:
type: array
items:
type: string
description: 'IPTC media topic taxonomy paths identified in the article content. Each path represents a hierarchical category following the IPTC standard.
**Note**: The `iptc_tags_name` field is only available in the `v3_nlp_iptc_tags` subscription plan.
'
iptc_tags_id:
type: array
items:
type: string
description: 'IPTC media topic numeric codes identified in the article content. These codes correspond to the standardized IPTC media topic taxonomy.
**Note**: The `iptc_tags_id` field is only available in the `v3_nlp_iptc_tags` subscription plan.
'
iab_tags_name:
type: array
items:
type: string
description: 'IAB content taxonomy paths identified in the article content. Each path represents a hierarchical category following the IAB content standard.
**Note**: The `iab_tags_name` field is only available in the `v3_nlp_iptc_tags` subscription plan.
'
ContentSentimentMax:
type: number
format: float
minimum: -1.0
maximum: 1.0
description: '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](https://www.newscatcherapi.com/docs/news-api/guides-and-concepts/nlp-features).
'
example: 0.5
Theme:
type: string
example: Finance,Tech
description: 'Filters articles based on their general topic, as determined by NLP analysis. To select multiple themes, use a comma-separated string.
To learn more, see [NLP features](https://www.newscatcherapi.com/docs/news-api/guides-and-concepts/nlp-features).
Available options: `Business`, `Economics`, `Entertainment`, `Finance`, `Health`, `Politics`, `Science`, `Sports`, `Tech`, `Crime`, `Financial Crime`, `Lifestyle`, `Automotive`, `Travel`, `Weather`, `General`.
'
NamedEntityList:
type: array
description: A list of named entities identified in the article.
items:
type: object
properties:
entity_name:
type: string
description: The name of the entity identified in the article.
count:
type: integer
description: The number of times this entity appears in the article.
SentimentScores:
type: object
description: Sentiment scores for the article's title and content.
properties:
title:
type: number
format: float
description: The sentiment score for the article title (-1.0 to 1.0).
content:
type: number
format: float
description: The sentiment score for the article content (-1.0 to 1.0).
PageSize:
type: integer
minimum: 1
maximum: 1000
default: 100
description: 'The number of articles to return per page.
'
example: 50
HasNlp:
type: boolean
default: false
description: 'If true, filters results to include only articles that have NLP data.
**Note**: NLP data is only available for articles indexed from July 2023 onward. Applying this filter to a date range that predates July 2023 returns zero results.
To learn more, see [NLP features](https://www.newscatcherapi.com/docs/news-api/guides-and-concepts/nlp-features).
'
example: true
Error:
type: object
properties:
message:
type: string
description: A detailed description of the error.
status_code:
type: integer
description: The HTTP status code of the error.
status:
type: string
description: A short description of the status code.
required:
- message
- status_code
- status
IncludeNlpData:
type: boolean
default: false
description: 'If true, includes an NLP object for each article in the response. This object provides results of NLP analysis, including article theme, summary, sentiment, tags, and named entity recognition if available.
**Note**: NLP data is only available for articles indexed from July 2023 onward. For articles indexed before July 2023, the `nlp` field is returned as an empty object `{}`.
To learn more, see [NLP features](https://www.newscatcherapi.com/docs/news-api/guides-and-concepts/nlp-features).
'
example: true
BreakingNewsArticleEntity:
title: Breaking News Article Object
description: 'The data model representing a single article in the `Breaking news` search results.
'
required:
- title
- link
- domain_url
- full_domain_url
- parent_url
- rank
- id
- score
type: object
properties:
title:
title: Title
description: The title of the article.
type: string
author:
title: Author
description: The primary author of the article.
type: string
authors:
title: Authors
description: A list of authors of the article.
anyOf:
- type: array
items:
type: string
- type: string
journalists:
title: Journalists
description: A list of journalists associated with the article.
anyOf:
- type: array
items:
type: string
- type: string
- type: 'null'
published_date:
title: Published Date
description: The date the article was published.
type: string
published_date_precision:
title: Published Date Precision
description: The precision of the published date.
type: string
updated_date:
title: Updated Date
description: The date the article was last updated.
type:
- string
- 'null'
updated_date_precision:
title: Updated Date Precision
description: The precision of the updated date.
type:
- string
- 'null'
parse_date:
title: Parse Date
description: The date the article was parsed.
type:
- string
- 'null'
link:
title: Link
description: The URL link to the article.
type: string
domain_url:
title: Domain URL
description: The domain URL of the article.
type: string
full_domain_url:
title: Full Domain URL
description: The full domain URL of the article.
type: string
name_source:
title: Name Source
description: The name of the source where the article was published.
type: string
is_headline:
title: Is Headline
description: Indicates if the article is a headline.
type: boolean
paid_content:
title: Paid Content
description: Indicates whether the source labels the article as paywalled or requiring a subscription for full access.
type: boolean
parent_url:
title: Parent URL
description: The categorical URL of the article.
type: string
country:
title: Country
description: The country where the article was published.
type: string
rights:
title: Rights
description: The rights information for the article.
type: string
rank:
title: Rank
description: The rank of the article's source.
type: integer
media:
title: Media
description: The media associated with the article.
type: string
language:
title: Language
description: The language in which the article is written.
type: string
description:
title: Description
description: A brief description of the article.
type: string
content:
title: Content
description: The content of the article.
type: string
title_translated_en:
type:
- string
- 'null'
description: 'English translation of the article title. Available when setting the `include_translation_fields` parameter to `true`.
'
content_translated_en:
type:
- string
- 'null'
description: 'English translation of the article content. Available when setting the `include_translation_fields` parameter to `true`.
'
word_count:
title: Word Count
description: The word count of the article.
type: integer
default: 0
is_opinion:
title: Is Opinion
description: Indicates if the article is an opinion piece.
type: boolean
twitter_account:
title: Twitter Account
description: The Twitter account associated with the article.
type:
- string
- 'null'
all_links:
title: All Links
description: A list of all URLs mentioned in the article.
anyOf:
- type: array
items:
type: string
- type: string
default: []
all_domain_links:
title: All Domain Links
description: A list of all domain URLs mentioned in the article.
anyOf:
- type: array
items:
type: string
- type: string
default: []
nlp:
$ref: '#/components/schemas/NlpDataEntity'
id:
title: ID
description: The unique identifier for the article.
type: string
score:
title: Score
description: The relevance score of the article.
type: number
OrgEntityName:
type: string
description: "Filters articles that mention specific organization names, as identified by NLP analysis. \n\n- To specify multiple organizations, use `AND`, `OR`, `NOT` operators, and `\\\"` escape literals for exact matches. \n- To search in translations, combine with the translation options of the `search_in` parameter (e.g., `title_content_translated`).\n\nTo learn more, see [Search by entity](https://www.newscatcherapi.com/docs/news-api/how-to/search-by-entity).\n"
example: '"Apple Inc" OR Microsoft'
IncludeTranslationFields:
type: boolean
default: false
description: 'If true, includes English translation fields in the response (`title_translated_en`, `content_translated_en`, and NLP translation fields).
'
example: true
PerEntityName:
type: string
description: "Filters articles that mention specific person names, as identified by NLP analysis. \n\n- To specify multiple names, use `AND`, `OR`, `NOT` operators, and `\\\"` escape literals for exact matches. \n- To search in translations, combine with the translation options of the `search_in` parameter (e.g., `title_content_translated`).\n\nTo learn more, see [Search by entity](https://www.newscatcherapi.com/docs/news-api/how-to/search-by-entity).\n"
example: '"Elon Musk" OR "Jeff Bezos"'
SortBy:
type: string
enum:
- relevancy
- date
- rank
default: relevancy
description: 'The sorting order of the results. Possible values are:
- `relevancy`: The most relevant results first.
- `date`: The most recently published results first.
- `rank`: The results from the highest-ranked sources first.
'
example: date
BreakingNewsEventEntity:
title: Breaking News Event Object
description: 'The data model representing a breaking news event with its associated articles.
'
required:
- event_id
- articles_count
- articles
type: object
properties:
event_id:
title: Event ID
description: Unique identifier for the breaking news event/cluster.
type: string
articles_count:
title: Articles Count
description: Number of articles in this breaking news cluster.
type: integer
articles:
title: Articles
description: The articles associated with this breaking news event.
type: array
items:
$ref: '#/components/schemas/BreakingNewsArticleEntity'
default: []
MiscEntityName:
type: string
description: "Filters articles that mention other named entities not falling under person, organization, or location categories. Includes events, nationalities, products, works of art, and more.\n\n- To specify multiple entities, use `AND`, `OR`, `NOT` operators, and `\\\"` escape literals for exact matches. \n- To search in translations, combine with the translation options of the `search_in` parameter (e.g., `title_content_translated`).\n\nTo learn more, see [Search by entity](https://www.newscatcherapi.com/docs/news-api/how-to/search-by-entity).\n"
example: AWS OR "Microsoft Azure"
ContentSentimentMin:
type: number
format: float
minimum: -1.0
maximum: 1.0
description: '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](https://www.newscatcherapi.com/docs/news-api/guides-and-concepts/nlp-features).
'
example: -0.5
BaseSearchResponseDto:
title: Base Search Response
description: The base response model containing common fields for search operations.
required:
- status
- total_hits
- page
- total_pages
- page_size
type: object
properties:
status:
title: Status
description: The status of the response.
type: string
total_hits:
title: Total Hits
description: The total number of articles matching the search criteria.
type: integer
page:
title: Page
description: The current page number of the results.
type: integer
total_pages:
title: Total Pages
description: The total number of pages available for the given search criteria.
type: integer
page_size:
title: Page Size
description: The number of articles per page.
type: integer
NotTheme:
type: string
example: Crime,Sports
description: 'Inverse of the `theme` parameter. Excludes articles based on their general topic, as determined by NLP analysis. To exclude multiple themes, use a comma-separated string.
To learn more, see [NLP features](https://www.newscatcherapi.com/docs/news-api/guides-and-concepts/nlp-features).
'
Page:
type: integer
minimum: 1
default: 1
description: "The page number to scroll through the results. Use for pagination, as a single API response can return up to 1,000 articles. \n\nFor details, see [Retrieve large datasets](https://www.newscatcherapi.com/docs/news-api/how-to/retrieve-more-than-10k-articles)\n"
example: 2
TitleSentimentMin:
type: number
format: float
minimum: -1.0
maximum: 1.0
description: '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](https://www.newscatcherapi.com/docs/news-api/guides-and-concepts/nlp-features).
'
example: -0.5
BreakingNewsResponseDto:
title: Breaking News Response
description: "The response model for the breaking news requests. Response field behavior:\n- Required fields are guaranteed to be present and non-null. \n- Optional fields may be `null` or `undefined` if the data point is not presented or couldn't be extracted during processing.\n- 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.).\n- The `nlp` property within the article object `articles[n].nlp` is only available with NLP-enabled subscription plans.\n"
allOf:
- $ref: '#/components/schemas/BaseSearchResponseDto'
- type: object
properties:
breaking_news_events:
title: Breaking News Events
description: A list of breaking news events, each containing relevant articles.
type: array
items:
$ref: '#/components/schemas/BreakingNewsEventEntity'
default: []
user_input:
$ref: '#/components/schemas/UserInputDto'
TitleSentimentMax:
type: number
format: float
minimum: -1.0
maximum: 1.0
description: '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](https://www.newscatcherapi.com/docs/news-api/guides-and-concepts/nlp-features).
'
example: 0.5
responses:
UnauthorizedError:
description: Unauthorized - Authentication failed
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
message: The 'x-api-token' parameter has an invalid value. Please provide a valid API key.
status_code: 401
status: Unauthorized
ForbiddenError:
description: Forbidden - Server refuses action
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
message: Your plan request date range cannot be greater than 400 days
status_code: 403
status: Forbidden
RequestTimeoutError:
description: Request timeout
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
message: Request timed out after 30 seconds
status_code: 408
status: Request timeout
RateLimitError:
description: Too many requests - Rate limit exceeded
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
message: Max API requests concurrency reached
status_code: 429
status: Too many requests
BreakingNewsResponse:
description: A successful response containing breaking news articles with additional breaking news event information.
content:
application/json:
schema:
$ref: '#/components/schemas/BreakingNewsResponseDto'
BadRequestError:
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
message: Invalid JSON in request body
status_code: 400
status: Bad request
ValidationError:
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
message: Invalid date format
status_code: 422
status: Validation error
InternalServerError:
description: Internal server error
content:
text/plain:
schema:
type: string
example: Internal Server Error
parameters:
OrgEntityName:
name: ORG_entity_name
in: query
required: false
schema:
$ref: '#/components/schemas/OrgEntityName'
TopNArticles:
name: top_n_articles
in: query
schema:
$ref: '#/components/schemas/TopNArticles'
required: false
Page:
name: page
in: query
required: false
schema:
$ref: '#/components/schemas/Page'
TitleSentimentMin:
name: title_sentiment_min
in: query
required: false
schema:
$ref: '#/components/schemas/TitleSentimentMin'
PerEntityName:
name: PER_entity_name
in: query
required: false
schema:
$ref: '#/components/schemas/PerEntityName'
TitleSentimentMax:
name: title_sentiment_max
in: query
required: false
schema:
$ref: '#/components/schemas/TitleSentimentMax'
FromRank:
name: from_rank
in: query
required: false
schema:
$ref: '#/components/schemas/FromRank'
NotTheme:
name: not_theme
in: query
required: false
schema:
$ref: '#/components/schemas/NotTheme'
ContentSentimentMax:
name: content_sentiment_max
in: query
required: false
schema:
$ref: '#/components/schemas/ContentSentimentMax'
PageSize:
name: page_size
in: query
required: false
schema:
$ref: '#/components/schemas/PageSize'
HasNlp:
name: has_nlp
in: query
required: false
schema:
$ref: '#/components/schemas/HasNlp'
MiscEntityName:
name: MISC_entity_name
in: query
required: false
schema:
$ref: '#/components/schemas/MiscEntityName'
SortBy:
name: sort_by
in: query
required: false
schema:
$ref: '#/components/schemas/SortBy'
example: date
LocEntityName:
name: LOC_entity_name
in: query
required: false
schema:
$ref: '#/components/schemas/LocEntityName'
ContentSentimentMin:
name: content_sentiment_min
in: que
# --- truncated at 32 KB (35 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/newscatcher/refs/heads/main/openapi/newscatcher-breakingnews-api-openapi.yml