Newscatcher Sources API

openapi: 3.2.0
info:
  title: Newscatcher Sources API
  termsOfService: https://newscatcherapi.com/terms-of-service
  version: '1.0'
  description: 'Operations tagged Sources 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: Sources
  description: Operations to retrieve local news sources.
paths:
  /api/sources:
    post:
      tags:
      - Sources
      summary: Retrieve sources
      description: Retrieves the list of local news sources available in the database. Filterable by language, country, and theme.
      operationId: Sources_post
      requestBody:
        $ref: '#/components/requestBodies/SourceRequestBody'
      responses:
        '200':
          $ref: '#/components/responses/SourcesResponse'
        '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: sources
      x-fern-sdk-method-name: get
      tags:
      - Sources
      summary: Retrieve sources
      description: Retrieves a list of sources based on specified criteria such as language, country, rank, and more.
      operationId: sourcesGet
      parameters:
      - $ref: '#/components/parameters/Lang'
      - $ref: '#/components/parameters/Countries'
      - $ref: '#/components/parameters/PredefinedSources'
      - $ref: '#/components/parameters/SourceName'
      - $ref: '#/components/parameters/SourceUrl'
      - $ref: '#/components/parameters/IncludeAdditionalInfo'
      - $ref: '#/components/parameters/IsNewsDomain'
      - $ref: '#/components/parameters/NewsDomainType'
      - $ref: '#/components/parameters/NewsType'
      - $ref: '#/components/parameters/FromRank'
      - $ref: '#/components/parameters/ToRank'
      responses:
        '200':
          $ref: '#/components/responses/SourcesResponse_2'
        '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
components:
  schemas:
    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
    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
    Lang:
      oneOf:
      - type: string
      - type: array
        items:
          type: string
      description: 'The language(s) of the search. The only accepted format is the two-letter [ISO 639-1](https://en.wikipedia.org/wiki/ISO_639-1) code. To select multiple languages, use a comma-separated string or an array of strings.


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

        '
      example:
      - en
      - es
    SourcesResponseDto:
      title: Sources Response
      description: 'The response model for the `Sources` request.


        Response field behavior:

        - Required fields are guaranteed to be present and non-null.

        - Optional fields may be `null`/`undefined` if the data couldn''t be extracted during processing.

        '
      type: object
      required:
      - message
      - sources
      - user_input
      properties:
        message:
          type: string
          description: A message describing the result of the sources request.
        sources:
          type: array
          items:
            type: string
          description: A list of available local news sources.
        user_input:
          $ref: '#/components/schemas/SourcesUserInputDto'
    SourcesUserInputDto:
      title: Sources User Input
      description: The user input parameters used to search local news sources.
      type: object
      properties:
        lang:
          oneOf:
          - type: string
          - type: array
            items:
              type: string
          description: The language(s) of the retrieved sources.
        countries:
          oneOf:
          - type: string
          - type: array
            items:
              type: string
          description: The country or countries of the retrieved sources.
        theme:
          oneOf:
          - type: string
          - type: array
            items:
              type: string
          description: The theme(s) of the retrieved sources.
    SourcesRequestDto:
      type: object
      properties:
        lang:
          $ref: '#/components/schemas/Lang'
        countries:
          $ref: '#/components/schemas/Countries'
        theme:
          $ref: '#/components/schemas/Theme'
    Theme:
      oneOf:
      - type: string
      - type: array
        items:
          type: string
      description: "Filters articles based on their general topic, as determined by NLP analysis. To select multiple themes, use a comma-separated string or an array of strings. \n\nTo learn more, see [NLP features](https://www.newscatcherapi.com/docs/news-api/guides-and-concepts/nlp-features).\n\nAvailable options: `Business`, `Economics`, `Entertainment`, `Finance`, `Health`, `Politics`, `Science`, `Sports`, `Tech`, `Crime`, `Financial Crime`, `Lifestyle`, `Automotive`, `Travel`, `Weather`, `General`.\n"
      example:
      - Business
      - Finance
    Countries_2:
      oneOf:
      - type: string
        example: US,CA
      - type: array
        items:
          type: string
        example:
        - US
        - CA
      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).

        '
    SourcesResponseDto_2:
      title: Sources Response
      description: "The response model for a successful `Sources` request retrieving news sources matching the specified criteria. 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"
      required:
      - message
      - sources
      - user_input
      type: object
      properties:
        message:
          title: Message
          description: A message indicating the result of the request.
          type: string
        sources:
          title: Sources
          description: A list of news sources that match the specified criteria.
          type: array
          items:
            anyOf:
            - $ref: '#/components/schemas/SourceInfo'
            - type: string
        user_input:
          title: User Input
          description: The user input parameters for the request.
          type: object
    AdditionalSourceInfo:
      title: Additional Source Info
      description: The data model for additional information about a news source.
      type: object
      properties:
        nb_articles_for_7d:
          title: Nb Articles For 7D
          description: The number of articles published by the source in the last seven days.
          type: integer
        country:
          title: Country
          description: The country of origin of the news source.
          type: string
        rank:
          title: Rank
          description: The SEO rank of the news source.
          type: integer
        is_news_domain:
          title: Is News Domain
          description: Indicates whether the source is a news domain.
          type: boolean
        news_domain_type:
          title: News Domain Type
          description: The type of news domain.
          type: string
        news_type:
          title: News Type
          description: The category of news provided by the source.
          type: string
        robots_compliant:
          title: Robots Compliant
          description: 'Percentage of domain articles that comply with robots.txt scraping rules (0-100%).

            '
          type: string
          example: 100%
      example:
        nb_articles_for_7d: 153
        country: US
        rank: 117
        is_news_domain: true
        news_domain_type: Original Content
        news_type: General News Outlets
        robots_compliant: 100%
    SourceInfo:
      title: Source Info
      description: The data model for information about a news source.
      required:
      - domain_url
      type: object
      properties:
        name_source:
          title: Name Source
          description: The name of the news source.
          type: string
        domain_url:
          title: Domain Url
          description: The domain URL of the news source.
          type: string
        logo:
          title: Logo
          description: The logo of the news source.
          type: string
        additional_info:
          $ref: '#/components/schemas/AdditionalSourceInfo'
    IncludeAdditionalInfo:
      type: boolean
      description: 'If true, returns the following additional datapoints about each news source:

        - `nb_articles_for_7d`: The number of articles published by the source in the last week.

        - `country`: Source country of origin.

        - `rank`: SEO rank.

        - `is_news_domain`: Boolean indicating if the source is a news domain.

        - `news_domain_type`: Type of news domain (e.g., "Original Content").

        - `news_type`: Category of news (e.g., "General News Outlets").

        - `robots_compliant`: Percentage of domain articles that comply with robots.txt scraping rules (0-100%).

        '
      example: true
    IsNewsDomain:
      type: boolean
      description: 'If true, filters results to include only news domains.

        '
      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
    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
    SourceName:
      oneOf:
      - type: string
        example: sport, tech
      - type: array
        items:
          type: string
        example:
        - sport
        - tech
      description: 'Specifies terms to search within the source names. To specify multiple terms, use a comma-separated string or an array of strings.


        **Note**: The search does not require an exact match and returns all sources that include the specified terms anywhere in their names. You can use any word, phrase, or outlet name, such as `"sport"`, or `"new york times"`. For example, using `"sport"` as a term returns sources like `"Motorsport"`, `"Dot Esport"`, and `"Tuttosport"`.

        '
    PredefinedSources:
      oneOf:
      - type: string
        example: top 50 US, top 20 GB
      - type: array
        items:
          type: string
        example:
        - top 50 US
        - top 20 GB
      description: "Predefined top news sources per country. \n\nFormat: start with the word `top`, followed by the number of desired sources, and then the two-letter country code [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2). \n\nMultiple countries with the number of top sources can be specified as a comma-separated string or an array of strings.\n"
    NewsType:
      oneOf:
      - type: string
        example: General News Outlets,Tech News and Updates
      - type: array
        items:
          type: string
        example:
        - General News Outlets
        - Tech News and Updates
      description: 'Filters results based on the news type. Multiple types can be specified using a comma-separated string or an array of strings.


        For a complete list of available news types, see [Enumerated parameters > News type](https://www.newscatcherapi.com/docs/news-api/api-reference/enumerated-parameters#news-type-news-type).

        '
    NewsDomainType:
      type: string
      enum:
      - Original Content
      - Aggregator
      - Press Releases
      - Republisher
      - Other
      description: 'Filters results based on the news domain type. Possible values are:

        - `Original Content`: Sources that produce their own content.

        - `Aggregator`: Sources that collect content from various other sources.

        - `Press Releases`: Sources primarily publishing press releases.

        - `Republisher`: Sources that republish content from other sources.

        - `Other`: Sources that don''t fit into main categories.

        '
      example: Original Content
    Lang_2:
      oneOf:
      - type: string
        example: en,es
      - type: array
        items:
          type: string
        example:
        - en
        - es
      description: 'The language(s) of the search. The only accepted format is the two-letter [ISO 639-1](https://en.wikipedia.org/wiki/ISO_639-1) code. To select multiple languages, use a comma-separated string or an array of strings.


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

        '
    SourceUrl:
      oneOf:
      - type: string
        example: bbc.com,nytimes.com
      - type: array
        items:
          type: string
        example:
        - bbc.com
        - nytimes.com
      description: "The domains of the news publication to search for. To specify multiple news sources, \nuse a comma-separated string or an array of strings.\n\n**Caution**:  When specifying the `source_url` parameter, you can only use `include_additional_info` as an extra parameter.\n"
      example: bbc.com
  responses:
    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
    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
    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
    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
    SourcesResponse:
      description: Successful response containing the list of sources
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SourcesResponseDto'
    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
    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
    SourcesResponse_2:
      description: A successful response containing a list of news sources that match the specified criteria.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SourcesResponseDto_2'
    UnauthorizedError_2:
      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
  requestBodies:
    SourceRequestBody:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SourcesRequestDto'
    SourcesRequestBody:
      description: Request body for searching news sources based on specified criteria such as language, country, and more.
      required: true
      content:
        application/json:
          schema:
            type: object
            properties:
              lang:
                $ref: '#/components/schemas/Lang_2'
              countries:
                $ref: '#/components/schemas/Countries_2'
              predefined_sources:
                $ref: '#/components/schemas/PredefinedSources'
              source_name:
                $ref: '#/components/schemas/SourceName'
              source_url:
                $ref: '#/components/schemas/SourceUrl'
              include_additional_info:
                $ref: '#/components/schemas/IncludeAdditionalInfo'
              is_news_domain:
                $ref: '#/components/schemas/IsNewsDomain'
              news_domain_type:
                $ref: '#/components/schemas/NewsDomainType'
              news_type:
                $ref: '#/components/schemas/NewsType'
              from_rank:
                $ref: '#/components/schemas/FromRank'
              to_rank:
                $ref: '#/components/schemas/ToRank'
            example:
              predefined_sources: top 10 US
  parameters:
    SourceUrl:
      description: "The domain(s) of the news publication to search for. \n\n**Caution**:  When specifying the `source_url` parameter, \nyou can only use `include_additional_info` as an extra parameter.\n"
      name: source_url
      in: query
      required: false
      schema:
        type: string
      example: bbc.com
    IsNewsDomain:
      name: is_news_domain
      in: query
      required: false
      schema:
        $ref: '#/components/schemas/IsNewsDomain'
    PredefinedSources:
      description: "Predefined top news sources per country. \n\nFormat: start with the word `top`, followed by the number of desired sources, and then the two-letter country code [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2). \n\nMultiple countries with the number of top sources can be specified as a comma-separated string.\n"
      name: predefined_sources
      in: query
      required: false
      schema:
        type: string
        example: top 50 US, top 20 GB
    Lang:
      description: 'The language(s) of the search. The only accepted format is the two-letter [ISO 639-1](https://en.wikipedia.org/wiki/ISO_639-1) code. To select multiple languages, use a comma-separated string.


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

        '
      name: lang
      in: query
      required: false
      schema:
        type: string
        example: en,es
    SourceName:
      description: "Word or phrase to search within the source names. To specify multiple values, use a comma-separated string.\n\n**Note**: The search doesn't require an exact match and returns sources containing the specified terms in their names. You can use any word or phrase, like `\"sport\"` or `\"new york times\"`. \n\nFor example, `\"sport\"` returns sources such as `\"Motorsport\"`, `\"Dot Esport\"`, and `\"Tuttosport\"`.\n"
      name: source_name
      in: query
      required: false
      schema:
        type: string
        example: sport,tech
    FromRank:
      name: from_rank
      in: query
      required: false
      schema:
        $ref: '#/components/schemas/FromRank'
    IncludeAdditionalInfo:
      name: include_additional_info
      in: query
      required: false
      schema:
        $ref: '#/components/schemas/IncludeAdditionalInfo'
    Countries:
      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.


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

        '
      name: countries
      in: query
      required: false
      schema:
        type: string
        example: US,CA
    NewsDomainType:
      name: news_domain_type
      in: query
      required: false
      schema:
        $ref: '#/components/schemas/NewsDomainType'
    ToRank:
      name: to_rank
      in: query
      required: false
      schema:
        $ref: '#/components/schemas/ToRank'
    NewsType:
      description: 'Filters results based on the news type. Multiple types can be specified using a comma-separated string.


        For a complete list of available news types, see [Enumerated parameters > News type](https://www.newscatcherapi.com/docs/news-api/api-reference/enumerated-parameters#news-type-news-type).

        '
      name: news_type
      in: query
      required: false
      schema:
        type: string
      example: General News Outlets,Tech News and Updates
  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"
x-refined-from:
- newscatcher-local-news-api-openapi.yml
- newscatcher-news-api-openapi.yml