> ## Documentation Index > Fetch the complete documentation index at: https://newscatcherinc-docs.mintlify.site/docs/llms.txt > Use this file to discover all available pages before exploring further. # Retrieve sources > Retrieves a list of sources based on specified criteria such as language, country, rank, and more. ## OpenAPI ````yaml news-api-v3 get /api/sources openapi: 3.1.0 info: title: NewsCatcher News API description: > NewsCatcher News API provides programmatic access to a continuously updated global news index. It includes endpoints for article search, latest headlines, breaking news, author search, aggregation counts, and source discovery. ## Key features - **Full-text search**: Query articles by keyword, phrase, language, country, source, publication date, sentiment, and more using Boolean operators and advanced filters. - **NLP enrichment**: Articles include theme classification, sentiment scores, and named entity recognition (people, organizations, locations). - **Article clustering**: Group similar articles into clusters to reduce noise and surface unique stories. - **Deduplication**: Exclude duplicate articles from results to keep datasets clean and relevant. - **Source intelligence**: Discover and filter news sources by domain, type, rank, and geographic origin. For documentation, integration guides, and SDKs, visit the [developer portal](https://wwwnewscatcherapi.com/docs). termsOfService: https://newscatcherapi.com/terms-of-service contact: name: Maksym Sugonyaka email: maksym@newscatcherapi.com version: 3.24.0 servers: - url: https://v3-api.newscatcherapi.com description: News API production server security: - ApiKeyAuth: [] tags: - name: Search description: Operations to search for articles. externalDocs: description: Search for articles by keyword, language, country, source, and more. url: >- https://www.newscatcherapi.com/docs/news-api/api-reference/search/search-articles-get - name: LatestHeadlines description: Operations to retrieve latest headlines. externalDocs: description: >- Retrieve the latest headlines since a specified date, with filtering options. url: >- https://www.newscatcherapi.com/docs/news-api/api-reference/latest-headlines/retrieve-latest-headlines-get - name: BreakingNews description: Operations to retrieve breaking news articles. externalDocs: description: Retrieve breaking news articles. url: >- https://www.newscatcherapi.com/docs/news-api/api-reference/breaking-news/breaking-news-get - name: Authors description: Operations to search by author. externalDocs: description: Search for articles by author. url: >- https://www.newscatcherapi.com/docs/news-api/api-reference/authors/search-articles-by-author-get - 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 - name: Sources description: Operations to retrieve news sources. externalDocs: description: >- Retrieve the list of available sources, filtered by language and country. url: >- https://www.newscatcherapi.com/docs/news-api/api-reference/sources/retrieve-sources-get - name: AggregationCount description: Operations to aggregate news counts. externalDocs: description: >- Aggregate news counts based on specified criteria such as keyword, language, country, source, and more. url: >- https://www.newscatcherapi.com/docs/news-api/api-reference/aggregation-count/get-aggregation-count-by-interval-get - name: Subscription description: Operations to get subscription info. externalDocs: description: Retrieve information about your subscription plan. url: >- https://www.newscatcherapi.com/docs/news-api/api-reference/subscription/retrieve-subscription-plan-information-get externalDocs: description: Find out more about NewsCatcher News API url: https://www.newscatcherapi.com/docs paths: /api/sources: 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' '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: parameters: 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 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 PredefinedSources: description: > Predefined top news sources per country. Format: 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). Multiple countries with the number of top sources can be specified as a comma-separated string. name: predefined_sources in: query required: false schema: type: string example: top 50 US, top 20 GB SourceName: description: > Word or phrase to search within the source names. To specify multiple values, use a comma-separated string. **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"`. For example, `"sport"` returns sources such as `"Motorsport"`, `"Dot Esport"`, and `"Tuttosport"`. name: source_name in: query required: false schema: type: string example: sport,tech SourceUrl: description: | The domain(s) of the news publication to search for. **Caution**: When specifying the `source_url` parameter, you can only use `include_additional_info` as an extra parameter. name: source_url in: query required: false schema: type: string example: bbc.com IncludeAdditionalInfo: name: include_additional_info in: query required: false schema: $ref: '#/components/schemas/IncludeAdditionalInfo' IsNewsDomain: name: is_news_domain in: query required: false schema: $ref: '#/components/schemas/IsNewsDomain' NewsDomainType: name: news_domain_type in: query required: false schema: $ref: '#/components/schemas/NewsDomainType' 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 FromRank: name: from_rank in: query required: false schema: $ref: '#/components/schemas/FromRank' ToRank: name: to_rank in: query required: false schema: $ref: '#/components/schemas/ToRank' responses: SourcesResponse: description: >- A successful response containing a list of news sources that match the specified criteria. content: application/json: schema: $ref: '#/components/schemas/SourcesResponseDto' 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 UnauthorizedError: description: Unauthorized - Authentication failed content: application/json: schema: $ref: '#/components/schemas/Error' example: message: >- The 'x-api-token' parameter has an invalid value. Please provide a valid API key. status_code: 401 status: Unauthorized ForbiddenError: description: Forbidden - Server refuses action content: application/json: schema: $ref: '#/components/schemas/Error' example: message: Your plan request date range cannot be greater than 400 days status_code: 403 status: Forbidden RequestTimeoutError: description: Request timeout content: application/json: schema: $ref: '#/components/schemas/Error' example: message: Request timed out after 30 seconds status_code: 408 status: Request timeout ValidationError: description: Validation error content: application/json: schema: $ref: '#/components/schemas/Error' example: message: Invalid date format status_code: 422 status: Validation error 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 InternalServerError: description: Internal server error content: text/plain: schema: type: string example: Internal Server Error schemas: 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 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 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 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 SourcesResponseDto: title: Sources Response description: > The response model for a successful `Sources` request retrieving news sources matching the specified criteria. Response field behavior: - Required fields are guaranteed to be present and non-null. - Optional fields may be `null` or `undefined` if the data point is not presented or couldn't be extracted during processing. 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 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 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' 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% securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-token description: > API Key to authenticate requests. To access the API, include your API key in the `x-api-token` header. To obtain your API key, complete the [form](https://www.newscatcherapi.com/book-a-demo) or contact us directly. ````