openapi: 3.0.3 info: title: Local News AggregationCount SearchBy 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: SearchBy description: Operations to search local news by link, ID or RSS GUID. paths: /api/search_by: post: tags: - SearchBy summary: Search articles by identifiers description: Search for local news using article links, IDs, or RSS GUIDs. operationId: SearchBy_post requestBody: $ref: '#/components/requestBodies/SearchByRequestBody' responses: '200': $ref: '#/components/responses/SearchByResponse' '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: responses: SearchByResponse: description: 'A successful response containing articles that match the specified search criteria. ' content: application/json: schema: allOf: - $ref: '#/components/schemas/ArticleSearchAdvancedResponseDto' title: Search By Response UnauthorizedError: description: Unauthorized - Authentication failed content: application/json: schema: $ref: '#/components/schemas/Error' example: message: 'Invalid api key: INVALID_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 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 schemas: ArticleAdvancedResultEntity: title: Article Result (Advanced) allOf: - $ref: '#/components/schemas/BaseArticleEntity' - type: object properties: geonames: type: array items: $ref: '#/components/schemas/GeoNamesResponseEntity' description: 'A list of locations identified in the article, including detection methods, confidence, and localization scores. The location data adheres to the GeoNames format. ' GeoNamesLocationAdminEntity: type: object properties: geonames_id: type: string description: GeoNames ID for the administrative division. name: type: string description: 'Administrative division name. Use leading minus `-` to exclude the name. ' code: type: string description: Administrative division code. BaseArticleEntity: title: Article Result description: The data model representing the commont properties of the article object in the search results. Required fields are always non-null. Optional fields may be `null`/`undefined` if data extraction is unsuccessful. type: object required: - id - title - link - content - domain_url - published_date_precision - published_date - is_opinion - rank properties: id: type: string description: The unique identifier for the article. score: type: number format: float description: The relevance score of the article. title: type: string description: The title of the article. author: type: string description: The primary author of the article. link: type: string description: The URL link to the article. description: type: string description: A brief description of the article. media: type: string description: The URL of the media associated with the article, typically an image. content: type: string description: A snippet or summary of the article's content. authors: type: array items: type: string description: A list of authors of the article. published_date: type: string format: date-time description: The date and time the article was published. published_date_precision: type: string description: The precision of the published date. updated_date: type: string format: date-time description: The date and time the article was last updated. updated_date_precision: type: string description: The precision of the updated date. is_opinion: type: boolean description: Indicates if the article is an opinion piece. twitter_account: type: string nullable: true description: The Twitter account associated with the article. Can be `null`. domain_url: type: string description: The domain URL of the article's source. parent_url: type: string description: The parent URL of the article, typically representing the homepage of the source. word_count: type: integer description: The word count of the article. rank: type: integer description: The rank of the article's source. country: type: string description: The country code where the article was published. rights: type: string description: The rights information for the article, typically the domain name. language: type: string description: The language code in which the article is written. nlp: $ref: '#/components/schemas/NlpDataEntity' paid_content: type: boolean description: Indicates whether the source labels the article as paywalled or requiring a subscription for full access. title_translated_en: type: string description: 'English translation of the article title. Available when using the `search_in` parameter with the `title_translated` option or by setting the `include_translation_fields` parameter to `true`. ' nullable: true content_translated_en: type: string description: 'English translation of the article content. Available when using the `search_in` parameter with the `content_translated` option or by setting the `include_translation_fields` parameter to `true`. ' nullable: true ArticleSearchAdvancedResponseDto: title: Advanced Search Response description: "The response model for the `Search advanced`, `Latest headlines advanced`, and `Search by` requests.\n\nResponse field behavior:\n- Required fields are guaranteed to be present and non-null. \n- Optional fields may be `null`/`undefined` if the data 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" allOf: - $ref: '#/components/schemas/SearchResponseDto' - type: object properties: articles: type: array items: $ref: '#/components/schemas/ArticleAdvancedResultEntity' default: [] user_input: type: object NlpDataEntity: type: object description: Natural Language Processing data for the article. properties: theme: type: array items: 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. **Note**: The `new_embedding` field is only available in the `v3_local_news_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. ' Ids: oneOf: - type: string - type: array items: type: string description: 'The Newscatcher article ID (see the `_id` field in API response) or a list of article IDs to search for. To specify multiple IDs, use a comma-separated string or an array of strings. **Note**: You can use the `ids` parameter in combination with `links` or `rss_guids`, but at least one of these parameters must be provided. ' example: - 5f8d0d55b6e45e00179c6e7e - 5f8d0d55b6e45e00179c6e7f To: oneOf: - type: string format: date-time example: 2024-09-25 00:00:00 - type: string example: 1 day ago default: now description: "The ending point in time to search up to. Accepts date-time strings in ISO 8601 format and plain text strings. The default time zone is UTC. \n\nFormats with examples:\n- YYYY-mm-ddTHH:MM:SS: `2024-09-25T00:00:00`\n- YYYY-MM-dd: `2024-09-25`\n- YYYY/mm/dd HH:MM:SS: `2024/09/25 00:00:00`\n- YYYY/mm/dd: `2024/09/25`\n- English phrases: `1 day ago`, `today`, `now`\n\n**Note**: By default, applied to the publication date of the article. \nTo use the article's parse date instead, set the `by_parse_date` parameter to `true`.\n" example: 2024/09/25 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 minimum: -1.0 maximum: 1.0 description: The sentiment score for the article title (-1.0 to 1.0). content: type: number format: float minimum: -1.0 maximum: 1.0 description: The sentiment score for the article content (-1.0 to 1.0). RssGuids: oneOf: - type: string - type: array items: type: string description: "The RSS GUID (Globally Unique Identifier) or list of GUIDs to search for. To specify multiple GUIDs, use a comma-separated string or an array of strings. \n\nGUIDs are unique identifiers assigned to RSS feed items. They are often URLs or other unique strings.\n\n**Note**: You can use the `rss_guids` parameter in combination with `links` or `ids`, but at least one of these parameters must be provided.\n" example: - https://example.com/article1 - https://example.com/article2 PageSize: type: integer minimum: 1 maximum: 1000 default: 100 description: 'The number of articles to return per page. Range: `1` to `1000`. ' example: 100 SearchByRequestDto: type: object properties: links: $ref: '#/components/schemas/Links' ids: $ref: '#/components/schemas/Ids' rss_guids: $ref: '#/components/schemas/RssGuids' from_: $ref: '#/components/schemas/From' to_: $ref: '#/components/schemas/To' page: $ref: '#/components/schemas/Page' page_size: $ref: '#/components/schemas/PageSize' Coordinates: type: object description: Geographic coordinates for a location. properties: lat: type: number format: float nullable: true minimum: -90 maximum: 90 description: The latitude coordinate. lon: type: number format: float nullable: true minimum: -180 maximum: 180 description: The longitude coordinate. example: lat: 40.71427 lon: -74.00597 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 GeoNamesResponseEntity: type: object description: 'Represents a geographic location identified in an article using GeoNames structured data, including detection confidence and localization scores. ' required: - name - detection_methods properties: geonames_id: type: string description: 'The unique GeoNames identifier for the location. ' example: '5128581' name: type: string description: 'The canonical name of the location from GeoNames database. ' example: New York City country: type: string description: 'Two-letter ISO 3166-1 alpha-2 country code. ' example: US admin1: allOf: - $ref: '#/components/schemas/GeoNamesLocationAdminEntity' description: 'First-order administrative division (e.g., state, province, region). ' admin2: allOf: - $ref: '#/components/schemas/GeoNamesLocationAdminEntity' description: 'Second-order administrative division (e.g., county, department). ' admin3: allOf: - $ref: '#/components/schemas/GeoNamesLocationAdminEntity' description: 'Third-order administrative division (e.g., township, borough). ' admin4: allOf: - $ref: '#/components/schemas/GeoNamesLocationAdminEntity' description: 'Fourth-order administrative division (smallest administrative units). ' coordinates: allOf: - $ref: '#/components/schemas/Coordinates' feature_class: type: string description: 'GeoNames feature class (A: Administrative, H: Hydrographic, L: Area, P: Populated places, etc.). ' example: P feature_code: type: string description: 'Specific GeoNames feature code (e.g., PPL for populated place). ' example: PPL detection_methods: $ref: '#/components/schemas/DetectionMethods' reason: type: string description: 'Explanation of why this location was identified in the article context. ' example: New York City is mentioned as the location of the Icahn School of Medicine. localization_score: type: number format: float minimum: 0 maximum: 10 description: "Geographic focus score (0-10) indicating how locally relevant the article is to this location.\n- 10: Hyper-local with clear local impact\n- 7-9: Regional relevance\n- 4-6: Subnational relevance \n- 1-3: National relevance only\n- 0: No local relevance\n" example: 10.0 confidence_score: type: number format: float minimum: 0 maximum: 10 description: 'Model confidence score (0-10) in location identification accuracy. - 10: Certain match - 7-9: High confidence - 4-6: Medium confidence - 1-3: Low confidence - 0: Uncertain/not relevant ' example: 10.0 DetectionMethods: type: array items: type: string enum: - dedicated_source - local_section - regional_source - standard_format - proximity_mention - ai_extracted description: '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](/local-news-api/guides-and-concepts/location-detection-methods). ' example: - dedicated_source - proximity_mention - ai_extracted SearchResponseDto: title: Base Search Response required: - status - total_hits - page - total_pages - page_size type: object properties: status: title: Status description: The status of the response. type: string default: ok 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 From: oneOf: - type: string format: date-time example: 2024-09-24 00:00:00 - type: string example: 1 day ago default: 7 days ago description: "The starting point in time to search from. Accepts date-time strings in ISO 8601 format and plain text strings. The default time zone is UTC. \n\nFormats with examples:\n- YYYY-mm-ddTHH:MM:SS: `2024-09-24T00:00:00`\n- YYYY-MM-dd: `2024-09-24`\n- YYYY/mm/dd HH:MM:SS: `2024/09/24 00:00:00`\n- YYYY/mm/dd: `2024/09/24`\n- English phrases: `1 day ago`, `today`\n\n**Note**: By default, applied to the publication date of the article. \nTo use the article's parse date instead, set the `by_parse_date` parameter to `true`.\n" example: 2024/09/24 Page: type: integer minimum: 1 default: 1 description: '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. ' example: 2 Links: oneOf: - type: string - type: array items: type: string description: 'The article link or list of article links to search for. To specify multiple links, use a comma-separated string or an array of strings. **Note**: You can use the `links` parameter in combination with `ids` or `rss_guids`, but at least one of these parameters must be provided. ' example: https://nytimes.com/article1 requestBodies: SearchByRequestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SearchByRequestDto' securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-token description: "API Key to authenticate requests.\n\nTo access the API, include your API key in the `x-api-token` header. \nTo obtain your API key, complete the [form](https://www.newscatcherapi.com/book-a-demo) or contact us directly.\n" externalDocs: description: Find out more about Local News API url: https://www.newscatcherapi.com/docs/local-news-api/get-started/introduction