Retrieve sources

curl --request GET \
  --url https://v3-api.newscatcherapi.com/api/sources \
  --header 'x-api-token: <api-key>'

const options = {method: 'GET', headers: {'x-api-token': '<api-key>'}};

fetch('https://v3-api.newscatcherapi.com/api/sources', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://v3-api.newscatcherapi.com/api/sources",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "x-api-token: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://v3-api.newscatcherapi.com/api/sources"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("x-api-token", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://v3-api.newscatcherapi.com/api/sources")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["x-api-token"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "message": "<string>",
  "sources": [
    {
      "domain_url": "<string>",
      "name_source": "<string>",
      "logo": "<string>",
      "additional_info": {
        "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%"
      }
    }
  ],
  "user_input": {}
}

{
  "message": "Invalid JSON in request body",
  "status_code": 400,
  "status": "Bad request"
}

{
  "message": "The 'x-api-token' parameter has an invalid value. Please provide a valid API key.",
  "status_code": 401,
  "status": "Unauthorized"
}

{
  "message": "Your plan request date range cannot be greater than 400 days",
  "status_code": 403,
  "status": "Forbidden"
}

{
  "message": "Request timed out after 30 seconds",
  "status_code": 408,
  "status": "Request timeout"
}

{
  "message": "Invalid date format",
  "status_code": 422,
  "status": "Validation error"
}

{
  "message": "Max API requests concurrency reached",
  "status_code": 429,
  "status": "Too many requests"
}

Internal Server Error

GET

api

sources

Retrieve sources

curl --request GET \
  --url https://v3-api.newscatcherapi.com/api/sources \
  --header 'x-api-token: <api-key>'

const options = {method: 'GET', headers: {'x-api-token': '<api-key>'}};

fetch('https://v3-api.newscatcherapi.com/api/sources', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://v3-api.newscatcherapi.com/api/sources",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "x-api-token: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://v3-api.newscatcherapi.com/api/sources"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("x-api-token", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://v3-api.newscatcherapi.com/api/sources")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["x-api-token"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "message": "<string>",
  "sources": [
    {
      "domain_url": "<string>",
      "name_source": "<string>",
      "logo": "<string>",
      "additional_info": {
        "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%"
      }
    }
  ],
  "user_input": {}
}

{
  "message": "Invalid JSON in request body",
  "status_code": 400,
  "status": "Bad request"
}

{
  "message": "The 'x-api-token' parameter has an invalid value. Please provide a valid API key.",
  "status_code": 401,
  "status": "Unauthorized"
}

{
  "message": "Your plan request date range cannot be greater than 400 days",
  "status_code": 403,
  "status": "Forbidden"
}

{
  "message": "Request timed out after 30 seconds",
  "status_code": 408,
  "status": "Request timeout"
}

{
  "message": "Invalid date format",
  "status_code": 422,
  "status": "Validation error"
}

{
  "message": "Max API requests concurrency reached",
  "status_code": 429,
  "status": "Too many requests"
}

Internal Server Error

Authorizations

x-api-token

string

header

required

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 or contact us directly.

Query Parameters

lang

string

The language(s) of the search. The only accepted format is the two-letter ISO 639-1 code. To select multiple languages, use a comma-separated string.

To learn more, see Enumerated parameters > Language.

Example:

"en,es"

countries

string

The countries where the news publisher is located. The accepted format is the two-letter ISO 3166-1 alpha-2 code. To select multiple countries, use a comma-separated string.

To learn more, see Enumerated parameters > Country.

Example:

"US,CA"

predefined_sources

string

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.

Multiple countries with the number of top sources can be specified as a comma-separated string.

Example:

"top 50 US, top 20 GB"

source_name

string

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".

Example:

"sport,tech"

source_url

string

The domain(s) of the news publication to search for.

Caution: When specifying the source_url parameter, you can only use include_additional_info and content_type as extra parameters.

include_additional_info

boolean

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

is_news_domain

boolean

If true, filters results to include only news domains.

Example:

true

news_domain_type

Filters results based on the news domain type. Multiple types can be specified using a comma-separated string or an array of strings. 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"

news_type

string

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.

content_type

string

Counts only articles of the given content types when ranking sources. The order of the results, nb_articles_for_7d, and the minimum of 5 articles per source apply to matching articles only, so a source with fewer matching articles is left out. To select multiple content types, use a comma-separated string. Values are case-insensitive.

Available options: news_report, analysis, interview, opinion, press_release, listicle, service, commerce, review, autogen, seo_spam, obituary, ugc, non_article. Shortcuts: news selects news_report, analysis, and interview; all applies no filter.

Note: You can combine content_type with source_url and predefined_sources. It is not enough on its own: send at least one of lang, countries, source_url, source_name, or predefined_sources.

To learn more, see Content types.

Example:

"news"

from_rank

integer<int32>

default:1

The lowest boundary of the rank of a news website to filter by. A lower rank indicates a more popular source.

Required range: 1 <= x <= 999999

Example:

100

to_rank

integer<int32>

default:999999

The highest boundary of the rank of a news website to filter by. A lower rank indicates a more popular source.

Required range: 1 <= x <= 999999

Example:

100

Response

A successful response containing a list of news sources that match the specified criteria.

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.

message

string

required

A message indicating the result of the request.

sources

(Source Info · object | string)[]

required

A list of news sources that match the specified criteria.

The data model for information about a news source.

Show child attributes

user_input

User Input · object

required

The user input parameters for the request.

Get started

Guides and concepts

How to

Troubleshooting

API Reference

Integrations

Libraries

Retrieve sources

Authorizations

Query Parameters

Response