Newscatcher LatestHeadlines API

openapi: 3.2.0
info:
  title: Newscatcher Latest Headlines API
  termsOfService: https://newscatcherapi.com/terms-of-service
  version: '1.0'
  description: 'Operations tagged LatestHeadlines across 2 of this provider''s published API definitions: newscatcher-local-news-api-openapi.yml, newscatcher-news-api-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://local-news.newscatcherapi.com
  description: Local News API production server
- url: https://v3-api.newscatcherapi.com
  description: News API production server
security:
- ApiKeyAuth: []
tags:
- name: LatestHeadlines
  description: Operations to retrieve local news latest headlines. Includes both standard location filtering and advanced GeoNames filtering.
paths:
  /api/latest_headlines:
    post:
      tags:
      - LatestHeadlines
      summary: Retrieve latest headlines
      description: Retrieves the most recent news headlines for the specific locations and times. You can filter results by language, source, theme, and more.
      operationId: LatestHeadlines_post
      requestBody:
        $ref: '#/components/requestBodies/LatestHeadlinesRequestBody'
      responses:
        '200':
          $ref: '#/components/responses/LatestHeadlinesResponse'
        '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'
    get:
      x-fern-sdk-group-name: latest_headlines
      x-fern-sdk-method-name: get
      tags:
      - LatestHeadlines
      summary: Retrieve latest headlines
      description: Retrieves the latest headlines for the specified time period. You can filter results by language, country, source, and more.
      operationId: latestHeadlinesGet
      parameters:
      - $ref: '#/components/parameters/When'
      - $ref: '#/components/parameters/ByParseDate'
      - $ref: '#/components/parameters/SortBy'
      - $ref: '#/components/parameters/Lang'
      - $ref: '#/components/parameters/NotLang'
      - $ref: '#/components/parameters/Countries'
      - $ref: '#/components/parameters/NotCountries'
      - $ref: '#/components/parameters/PredefinedSources'
      - $ref: '#/components/parameters/Sources'
      - $ref: '#/components/parameters/NotSources'
      - $ref: '#/components/parameters/NotAuthorName'
      - $ref: '#/components/parameters/RankedOnly'
      - $ref: '#/components/parameters/IsHeadline'
      - $ref: '#/components/parameters/IsOpinion'
      - $ref: '#/components/parameters/IsPaidContent'
      - $ref: '#/components/parameters/ParentUrl'
      - $ref: '#/components/parameters/AllLinks'
      - $ref: '#/components/parameters/AllDomainLinks'
      - $ref: '#/components/parameters/AllLinksText'
      - $ref: '#/components/parameters/WordCountMin'
      - $ref: '#/components/parameters/WordCountMax'
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/PageSize'
      - $ref: '#/components/parameters/ClusteringEnabled'
      - $ref: '#/components/parameters/ClusteringVariable'
      - $ref: '#/components/parameters/ClusteringThreshold'
      - $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'
      - $ref: '#/components/parameters/IptcTags'
      - $ref: '#/components/parameters/NotIptcTags'
      - $ref: '#/components/parameters/IabTags'
      - $ref: '#/components/parameters/NotIabTags'
      - $ref: '#/components/parameters/CustomTags'
      - $ref: '#/components/parameters/RobotsCompliant'
      responses:
        '200':
          $ref: '#/components/responses/SearchResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError_2'
        '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'
    servers:
    - url: https://local-news.newscatcherapi.com
      description: Local News API production server
  /api/latest_headlines/advanced:
    post:
      tags:
      - LatestHeadlines
      summary: Retrieve latest headlines with GeoNames filtering
      description: 'Retrieves the most recent news headlines using structured GeoNames filtering with administrative hierarchy, coordinates, localization and confidence scores.

        '
      operationId: LatestHeadlinesAdvanced_post
      requestBody:
        $ref: '#/components/requestBodies/LatestHeadlinesAdvancedRequestBody'
      responses:
        '200':
          $ref: '#/components/responses/LatestHeadlinesAdvancedResponse'
        '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'
    servers:
    - url: https://local-news.newscatcherapi.com
      description: Local News API production server
components:
  schemas:
    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'
    Countries:
      oneOf:
      - type: string
      - type: array
        items:
          type: string
      description: 'The countries where the news publisher is located. The accepted format is the two-letter [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/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](https://www.newscatcherapi.com/docs/news-api/api-reference/enumerated-parameters#country-country-and-not-country).

        '
      example:
      - US
      - CA
    WordCountMin:
      type: integer
      minimum: 0
      description: 'The minimum number of words an article must contain. To be used for avoiding articles with small content.

        '
      example: 300
    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.

              '
    BaseRequestDto:
      type: object
      description: Common parameters shared across standard endpoints.
      properties:
        locations:
          type: array
          items:
            type: string
          description: '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:
          $ref: '#/components/schemas/DetectionMethods'
        lang:
          $ref: '#/components/schemas/Lang'
        countries:
          $ref: '#/components/schemas/Countries'
        sources:
          $ref: '#/components/schemas/Sources'
        not_sources:
          $ref: '#/components/schemas/NotSources'
        parent_url:
          $ref: '#/components/schemas/ParentUrl'
        is_paid_content:
          $ref: '#/components/schemas/IsPaidContent'
        page:
          $ref: '#/components/schemas/Page'
        page_size:
          $ref: '#/components/schemas/PageSize'
        word_count_min:
          $ref: '#/components/schemas/WordCountMin'
        word_count_max:
          $ref: '#/components/schemas/WordCountMax'
        clustering:
          $ref: '#/components/schemas/ClusteringEnabled'
        theme:
          $ref: '#/components/schemas/Theme'
        PER_entity_name:
          $ref: '#/components/schemas/PerEntityName'
        LOC_entity_name:
          $ref: '#/components/schemas/LocEntityName'
        MISC_entity_name:
          $ref: '#/components/schemas/MiscEntityName'
        ORG_entity_name:
          $ref: '#/components/schemas/OrgEntityName'
        title_sentiment_min:
          $ref: '#/components/schemas/TitleSentimentMin'
        title_sentiment_max:
          $ref: '#/components/schemas/TitleSentimentMax'
        content_sentiment_min:
          $ref: '#/components/schemas/ContentSentimentMin'
        content_sentiment_max:
          $ref: '#/components/schemas/ContentSentimentMax'
        include_translation_fields:
          $ref: '#/components/schemas/IncludeTranslationFields'
    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
    LatestHeadlinesRequestDto:
      allOf:
      - type: object
        properties:
          when:
            $ref: '#/components/schemas/When'
      - $ref: '#/components/schemas/BaseRequestDto'
    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
    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"
    Coordinates:
      type: object
      description: Geographic coordinates for a location.
      properties:
        lat:
          type:
          - number
          - 'null'
          format: float
          minimum: -90
          maximum: 90
          description: The latitude coordinate.
        lon:
          type:
          - number
          - 'null'
          format: float
          minimum: -180
          maximum: 180
          description: The longitude coordinate.
      example:
        lat: 40.71427
        lon: -74.00597
    ClusteringSearchResponseDto:
      title: Clustered Search Response
      description: "The response model when clustering is enabled, grouping similar articles into clusters. Applies to the `Search` and `Latest headlines` 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
        required:
        - clusters_count
        - agg_clusters
        - clusters
        - user_input
        properties:
          clusters_count:
            type: integer
            description: The total number of clusters in the search results.
          agg_clusters:
            type: array
            items:
              type: string
            description: A list of cluster IDs that contain articles from major news aggregators, such as msn.com, yahoo.com, pr.com.
          clusters:
            type: object
            additionalProperties:
              $ref: '#/components/schemas/ClusterEntity'
            description: A dictionary of cluster IDs mapped to their respective cluster entities.
          user_input:
            title: User Input
            description: The user input parameters for the search.
            type: object
    ClusterAdvancedEntity:
      title: Cluster Entity (Advanced)
      type: object
      required:
      - articles
      - agg_cluster
      - original_cluster_size
      - cluster_size
      properties:
        articles:
          type: array
          items:
            $ref: '#/components/schemas/ClusterArticleAdvancedResultEntity'
        agg_cluster:
          type: boolean
        original_cluster_size:
          type: integer
        cluster_size:
          type: integer
    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
    ParentUrl:
      oneOf:
      - type: string
      - type: array
        items:
          type: string
      description: '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
    BaseAdvancedRequestDto:
      type: object
      properties:
        geonames:
          $ref: '#/components/schemas/GeoNamesFilter'
        geonames_operator:
          $ref: '#/components/schemas/GeoNamesOperator'
        lang:
          $ref: '#/components/schemas/Lang'
        countries:
          $ref: '#/components/schemas/Countries'
        sources:
          $ref: '#/components/schemas/Sources'
        not_sources:
          $ref: '#/components/schemas/NotSources'
        parent_url:
          $ref: '#/components/schemas/ParentUrl'
        is_paid_content:
          $ref: '#/components/schemas/IsPaidContent'
        page:
          $ref: '#/components/schemas/Page'
        page_size:
          $ref: '#/components/schemas/PageSize'
        word_count_min:
          $ref: '#/components/schemas/WordCountMin'
        word_count_max:
          $ref: '#/components/schemas/WordCountMax'
        clustering:
          $ref: '#/components/schemas/ClusteringEnabled'
        theme:
          $ref: '#/components/schemas/Theme'
        PER_entity_name:
          $ref: '#/components/schemas/PerEntityName'
        LOC_entity_name:
          $ref: '#/components/schemas/LocEntityName'
        MISC_entity_name:
          $ref: '#/components/schemas/MiscEntityName'
        ORG_entity_name:
          $ref: '#/components/schemas/OrgEntityName'
        title_sentiment_min:
          $ref: '#/components/schemas/TitleSentimentMin'
        title_sentiment_max:
          $ref: '#/components/schemas/TitleSentimentMax'
        content_sentiment_min:
          $ref: '#/components/schemas/ContentSentimentMin'
        content_sentiment_max:
          $ref: '#/components/schemas/ContentSentimentMax'
        include_translation_fields:
          $ref: '#/components/schemas/IncludeTranslationFields'
    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). If false, excludes translation fields.

        '
      example: true
    GeoNamesEntity:
      type: object
      description: 'A single geographic location filter using GeoNames structured data. All provided fields within this object are combined with `AND` logic.

        '
      properties:
        geonames_id:
          type:
          - string
          - 'null'
          description: 'The unique GeoNames identifier for exact location matching.

            '
          example: '5128581'
        name:
          type:
          - string
          - 'null'
          description: 'The location name to search in articles. Use leading minus `-` to exclude names (e.g., `-Boston`). Supports wildcard `*` for partial matching when `enable_wildcard` is `true`.


            When the `search_with_alt_names` parameter is `true`, search in both canonical and alternative names from GeoNames database.

            '
          example: New York City
        country:
          type:
          - string
          - 'null'
          description: 'Two-letter [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country code.


            To learn more, see [Enumerated parameters > Country](https://www.newscatcherapi.com/docs/news-api/api-reference/enumerated-parameters#country-country-and-not-country).

            '
          example: US
        admin1:
          allOf:
          - $ref: '#/components/schemas/GeoNamesLocationAdminEntity'
          description: 'First-order administrative division filter (e.g., states in US, provinces in Canada, regions in Italy).

            '
          example:
            name: California
            code: CA
            geonames_id: '5332921'
        admin2:
          allOf:
          - $ref: '#/components/schemas/GeoNamesLocationAdminEntity'
          description: 'Second-order administrative division filter (e.g., counties in the US, departments in France).

            '
          example:
            name: Los Angeles County
            geonames_id: '5368361'
        admin3:
          allOf:
          - $ref: '#/components/schemas/GeoNamesLocationAdminEntity'
          description: 'Third-order administrative division filter (e.g., townships, boroughs, smaller regional divisions).

            '
          example:
            name: Manhattan
            geonames_id: '5125771'
        admin4:
          allOf:
          - $ref: '#/components/schemas/GeoNamesLocationAdminEntity'
          description: 'Fourth-order administrative division filter (smallest administrative units).

            '
          example:
            name: Downtown
        lat:
          type:
          - object
          - 'null'
          description: The latitude range to filter by. Can be `null`.
          properties:
            min:
              type: number
              format: float
              minimum: -90
              maximum: 90
              description: Minimum latitude (inclusive).
            max:
              type: number
              format: float
              minimum: -90
              maximum: 90
              description: Maximum latitude (inclusive).
          example:
            min: 37.0
            max: 38.5
        lon:
          type:
          - object
          - 'null'
          description: The longitude range to filter by. Can be `null`.
          properties:
            min:
              type: number
              format: float
              minimum: -180
              maximum: 180
              description: Minimum longitude (inclusive).
            max:
              type: number
              format: float
              minimum: -180
              maximum: 180
              description: Maximum longitude (inclusive).
          example:
            min: -123.0
            max: -121.5
        feature_class:
          type:
          - string
          - 'null'
          description: "GeoNames feature class. Main classes: \n- `A`: Administrative\n- `H`: Hydrographic\n- `L`: Area\n- `P`: Populated places\n- `R`: Roads/rail\n- `S`: Spots/buildings\n- `T`: Topography\n- `U`: Undersea\n- `V`: Vegetation\n"
          example: A
        feature_code:
          type:
          - string
          - 'null'
          description: 'Specific GeoNames feature code (e.g., `PPL` for populated place, `PPLA` for administrative seat). Supports wildcards.

            '
          example: PPL
        detection_methods:
          $ref: '#/components/schemas/DetectionMethods'
        localization_score:
          allOf:
          - $ref: '#/components/schemas/RangeModel'
          description: 'Filter by geographic focus score (0-10):

            - 10: Hyper-local — specific town or neighborhood named with clear local impact

            - 7–9: Regional — nearby city, metro, or administrative region mentioned with some local detail

            - 4–6: Subnational — province/state-level reference; town may be named but with limited context

            - 1–3: National or broader — only national relevance; town appears only in passing

            - 0: None — no mention or not relevant to the location

            '
        confidence_score:
          allOf:
          - $ref: '#/components/schemas/RangeModel'
          description: 'Filter by model''s confidence in location relevance (0-10):

            - 10: Certain — Clear, unambiguous match; location is definitely relevant

            - 7–9: High — Strong indications of relevance, but not absolute certainty

            - 4–6: Medium — Some evidence or indirect relevance, but inconclusive

            - 1–3: Low — Weak signal or unlikely relevance

            - 0: Certain Not — Confident the location is not mentioned or relevant

            '
        search_with_alt_names:
          type: boolean
          default: false
          description: 'If true, expands location search to alternative names, such as abbreviations, local language names, historical names, and other variants stored in the GeoNames database. For example, `"NYC"` finds articles about `"New York City"`. If false, searches only in canonical location names.


            **Note**: This setting affects all location names within the `geonames` object, including the `name` field and all administrative-level names (`admin1.name`, `admin2.name`, etc.).

            '
          example: true
        enable_wildcard:
          type: boolean
          default: false
          description: 'If true, enables wildcard matching using `*` for partial matching location names. If false, requires exact matching.


            **Note**: This setting affects all location names within the `geonames` object, including the `name` field and all administrative-level names (`admin1.name`, `admin2.name`, etc.).

            '
          example: false
    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).
    RangeModel:
      type: object
      description: Numeric range filter with minimum and/or maximum values (inclusive).
      properties:
        min:
          type: number
          minimum: 0
          maximum: 10
          description: Minimum value (inclusive).
        max:
          type: number
          minimum: 0
          maximum: 10
          description: Maximum value (inclusive).
      example:
        min: 7
        max: 10
    ArticleResultEntity:
      title: Article Result
      allOf:
      - $ref: '#/components/schemas/BaseArticleEntity'
      - type: object
        properties:
          locations:
            type: array
            items:
              $ref: '#/components/schemas/LocationEntity'
            description: "Simple location data with detection methods. \nFor structured GeoNames data, use the advanced endpoints.\n"
    ArticleSearchResponseDto:
      title: Search Response
      description: "The response model for the `Search`, `Latest headlines`, and `Search by` requests, including search results and metadata.\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:
            title: Articles
            description: A list of articles matching the search criteria.
            type: array
            items:
              $ref: '#/components/schemas/ArticleResultEntity'
            default: []
          user_input:
            title: User Input
            description: The user input parameters for the search.
            type: object
    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
    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.
    ClusterArticleAdvancedResultEntity:
      title: Cluster Article Result (Advanced)
      allOf:
      - $ref: '#/components/schemas/ArticleAdvancedResultEntity'
      - type: object
        required:
        - cluster_id
        - cluster_rank
        properties:
          cluster_id:
            type: string
          cluster_rank:
            type: integer
    IsPaidContent:
      type: boolean
      description: 'Filters articles by content completeness.


        If false, returns only articles for which full-text content is publicly available. If true, returns all indexed articles, including those where only partial content is publicly available (e.g., headlines, summaries, or preview paragraphs from paywalled sources).


        **Note**: NewsCatcher indexes content that is publicly accessible and available for crawling in accordance with publisher access controls (e.g., robots.txt and similar mechanisms). For paywalled sources, only content that publishers make publicly available (such as headlines, summaries, or preview text) is indexed. NewsCatcher does not bypass paywalls, authentication systems, or other technical access restric

# --- truncated at 32 KB (107 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/newscatcher/refs/heads/main/openapi/newscatcher-latestheadlines-api-openapi.yml