openapi: 3.0.3
info:
  title: Local News AggregationCount SearchByLink 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: SearchByLink
  description: Operations to search by link or ID.
  externalDocs:
    description: Search for articles by link or ID.
    url: https://www.newscatcherapi.com/docs/news-api/api-reference/search-by-link/search-articles-by-links-or-ids-get
paths:
  /api/search_by_link:
    get:
      x-fern-sdk-group-name: search_by_link
      x-fern-sdk-method-name: get
      tags:
      - SearchByLink
      summary: Search articles by links or IDs
      description: Searches for articles based on specified links or IDs. You can filter results by date range.
      operationId: searchByLinkGet
      parameters:
      - $ref: '#/components/parameters/Ids'
      - $ref: '#/components/parameters/Links'
      - name: from_
        in: query
        required: false
        schema:
          allOf:
          - $ref: '#/components/schemas/From'
          default: 1 month ago
      - $ref: '#/components/parameters/To'
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/PageSize'
      - $ref: '#/components/parameters/RobotsCompliant'
      responses:
        '200':
          $ref: '#/components/responses/SearchByLinkResponse'
        '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: search_by_link
      x-fern-sdk-method-name: post
      tags:
      - SearchByLink
      summary: Search articles by links or IDs
      description: Searches for articles using their ID(s) or link(s).
      operationId: searchByLinkPost
      requestBody:
        $ref: '#/components/requestBodies/SearchByLinkRequestBody'
      responses:
        '200':
          $ref: '#/components/responses/SearchByLinkResponse'
        '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:
    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
    SearchByLinkResponse:
      description: A successful response containing articles that match the provided links or IDs.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SearchResponseDto'
    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
  parameters:
    RobotsCompliant:
      name: robots_compliant
      in: query
      required: false
      schema:
        $ref: '#/components/schemas/RobotsCompliant'
    Page:
      name: page
      in: query
      required: false
      schema:
        $ref: '#/components/schemas/Page'
    Ids:
      description: "The Newscatcher article ID (corresponds to the `_id` field in API response) or a list of article IDs to search for. To specify multiple IDs, use a comma-separated string. \n\n**Caution**: You can use either the `links` or the `ids` parameter, but not both at the same time.\n"
      name: ids
      in: query
      required: false
      schema:
        type: string
        example: 5f8d0d55b6e45e00179c6e7e
    PageSize:
      name: page_size
      in: query
      required: false
      schema:
        $ref: '#/components/schemas/PageSize'
    Links:
      description: 'The article link or list of article links to search for. To specify multiple links, use a comma-separated string.


        **Caution**: You can use either the `links` or the `ids` parameter, but not both at the same time.

        '
      name: links
      in: query
      required: false
      schema:
        type: string
        example: https://nytimes.com/article1,https://bbc.com/article2
    To:
      name: to_
      in: query
      required: false
      schema:
        $ref: '#/components/schemas/To'
  schemas:
    ArticlesDto:
      title: Articles
      description: A list of articles matching the search criteria.
      type: array
      items:
        $ref: '#/components/schemas/ArticleEntity'
      default: []
    UserInputDto:
      type: object
      description: The user input parameters for the request.
      additionalProperties: true
    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.

            '
    Ids:
      oneOf:
      - type: string
        example: 5f8d0d55b6e45e00179c6e7e,5f8d0d55b6e45e00179c6e7f
      - type: array
        items:
          type: string
        example:
        - 5f8d0d55b6e45e00179c6e7e
        - 5f8d0d55b6e45e00179c6e7f
      description: 'The Newscatcher article ID (corresponds to 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.


        **Caution**: You can use either the `links` or the `ids` parameter, but not both at the same time.

        '
    To:
      oneOf:
      - type: string
        example: now
      - type: string
        format: date-time
        example: 2024-01-01 00:00:00
      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-07-01T00:00:00`\n- YYYY-MM-dd: `2024-07-01`\n- YYYY/mm/dd HH:MM:SS: `2024/07/01 00:00:00`\n- YYYY/mm/dd: `2024/07/01`\n- English phrases: `1 day ago`, `now`\n- Duration shorthand: `7d`, `30d`, `24h`, `48h`\n\n**Note**: By default, applied to the publication date of the article. To use the article's parse date instead, set the `by_parse_date` parameter to `true`.\n"
      default: now
    RobotsCompliant:
      type: boolean
      description: 'If true, returns only articles that comply with the publisher''s robots.txt rules. If false, returns only articles that do not comply with robots.txt rules. If omitted, returns all articles regardless of compliance status.

        '
      example: true
    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
    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
    ArticleEntity:
      title: Article Object
      description: The data model representing a single article in the 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 using the `search_in` parameter with the `title_translated` option or by setting the `include_translation_fields` parameter to `true`.

            '
        content_translated_en:
          type:
          - string
          - 'null'
          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`.

            '
        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: []
        all_links_data:
          title: All Links Data
          description: 'Detailed information about all links mentioned in the article, including link URL, domain, and anchor text. Only present when the `all_links_text` parameter is used in the request.

            '
          type: array
          items:
            $ref: '#/components/schemas/AllLinksDataItem'
          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
        robots_compliant:
          title: Robots Compliant
          description: 'True if the article content can be safely accessed according to the publisher''s robots.txt rules; false otherwise.

            '
          type: boolean
          example: true
        custom_tags:
          title: Custom Tags
          description: An object that contains custom tags associated with an article, where each key is a taxonomy name, and the value is an array of tags.
          type: object
          additionalProperties:
            type: array
            items:
              type: string
          default: {}
        additional_domain_info:
          $ref: '#/components/schemas/AdditionalDomainInfoEntity'
    SearchResponseDto:
      title: Search Response
      description: "The response model for the search requests applies to the `Search`, `Latest Headlines`, `Search by link`, and `Authors` endpoints. 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:
          articles:
            $ref: '#/components/schemas/ArticlesDto'
          user_input:
            $ref: '#/components/schemas/UserInputDto'
    AllLinksDataItem:
      title: Link Data Item
      description: Detailed information about a link found in an article.
      required:
      - domain_url
      - link
      - text
      type: object
      properties:
        domain_url:
          title: Domain URL
          description: The domain of the linked URL.
          type: string
          example: amazon.de
        link:
          title: Link
          description: The complete URL of the link.
          type: string
          example: https://www.amazon.de/s?k=Künstliche+Intelligenz
        text:
          title: Text
          description: The anchor text of the link.
          type: string
          example: KI Brillen
    From:
      oneOf:
      - type: string
        format: date-time
        example: 2024-07-01 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-07-01T00:00:00`\n- YYYY-MM-dd: `2024-07-01`\n- YYYY/mm/dd HH:MM:SS: `2024/07/01 00:00:00`\n- YYYY/mm/dd: `2024/07/01`\n- English phrases: `7 day ago`, `today`\n- Duration shorthand: `7d`, `30d`, `24h`, `48h`\n\n**Note**: By default, applied to the publication date of the article. To use the article's parse date instead, set the `by_parse_date` parameter to `true`.\n"
      example: 2021/01/01
    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
    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
    Links:
      oneOf:
      - type: string
        example: https://nytimes.com/article1, https://bbc.com/article2
      - type: array
        items:
          type: string
        example:
        - https://nytimes.com/article1
        - https://bbc.com/article2
      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.


        **Caution**: You can use either the `links` or the `ids` parameter, but not both at the same time.

        '
      example: https://nytimes.com/article1
    AdditionalDomainInfoEntity:
      title: Additional Domain Info
      description: Additional information about the domain of the article.
      type: object
      properties:
        is_news_domain:
          title: Is News Domain
          description: Indicates whether the domain is a news domain.
          type: boolean
        news_type:
          title: News Type
          description: The type of news content provided by the domain.
          type: string
        news_domain_type:
          title: News Domain Type
          description: The type of news domain.
          type: string
      example:
        is_news_domain: true
        news_type: News and Blogs
        news_domain_type: Original Content
  requestBodies:
    SearchByLinkRequestBody:
      description: Request body for searching articles based on specified links or IDs.
      required: true
      content:
        application/json:
          schema:
            type: object
            properties:
              ids:
                $ref: '#/components/schemas/Ids'
              links:
                $ref: '#/components/schemas/Links'
              from_:
                allOf:
                - $ref: '#/components/schemas/From'
                default: 1 month ago
              to_:
                $ref: '#/components/schemas/To'
              page:
                $ref: '#/components/schemas/Page'
              page_size:
                $ref: '#/components/schemas/PageSize'
              robots_compliant:
                $ref: '#/components/schemas/RobotsCompliant'
            example:
              links: https://www.reuters.com/business/energy/oil-prices-up-after-israeli-attacks-oversupply-caps-gains-2025-09-10/
  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