curl --request POST \
--url https://v3-api.newscatcherapi.com/api/sources \
--header 'Content-Type: application/json' \
--header 'x-api-token: <api-key>' \
--data '
{
"predefined_sources": "top 10 US"
}
'import requests
url = "https://v3-api.newscatcherapi.com/api/sources"
payload = { "predefined_sources": "top 10 US" }
headers = {
"x-api-token": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'x-api-token': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({predefined_sources: 'top 10 US'})
};
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 => "POST",
CURLOPT_POSTFIELDS => json_encode([
'predefined_sources' => 'top 10 US'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"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"
"strings"
"net/http"
"io"
)
func main() {
url := "https://v3-api.newscatcherapi.com/api/sources"
payload := strings.NewReader("{\n \"predefined_sources\": \"top 10 US\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-api-token", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://v3-api.newscatcherapi.com/api/sources")
.header("x-api-token", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"predefined_sources\": \"top 10 US\"\n}")
.asString();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::Post.new(url)
request["x-api-token"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"predefined_sources\": \"top 10 US\"\n}"
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 ErrorRetrieve sources
Retrieves the list of sources available in the database. You can filter the sources by language, country, and more.
curl --request POST \
--url https://v3-api.newscatcherapi.com/api/sources \
--header 'Content-Type: application/json' \
--header 'x-api-token: <api-key>' \
--data '
{
"predefined_sources": "top 10 US"
}
'import requests
url = "https://v3-api.newscatcherapi.com/api/sources"
payload = { "predefined_sources": "top 10 US" }
headers = {
"x-api-token": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'x-api-token': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({predefined_sources: 'top 10 US'})
};
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 => "POST",
CURLOPT_POSTFIELDS => json_encode([
'predefined_sources' => 'top 10 US'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"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"
"strings"
"net/http"
"io"
)
func main() {
url := "https://v3-api.newscatcherapi.com/api/sources"
payload := strings.NewReader("{\n \"predefined_sources\": \"top 10 US\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-api-token", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://v3-api.newscatcherapi.com/api/sources")
.header("x-api-token", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"predefined_sources\": \"top 10 US\"\n}")
.asString();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::Post.new(url)
request["x-api-token"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"predefined_sources\": \"top 10 US\"\n}"
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 ErrorAuthorizations
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.
Body
Request body for searching news sources based on specified criteria such as language, country, and more.
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 or an array of strings.
To learn more, see Enumerated parameters > Language.
"en,es"
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 or an array of strings.
To learn more, see Enumerated parameters > Country.
"US,CA"
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 or an array of strings.
"top 50 US, top 20 GB"
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".
"sport, tech"
The domains of the news publication to search for. To specify multiple news sources, use a comma-separated string or an array of strings.
Caution: When specifying the source_url parameter, you can only use include_additional_info and content_type as extra parameters.
"bbc.com"
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%).
true
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.
"Original Content"
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.
"General News Outlets,Tech News and Updates"
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 or an array of strings. 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.
"news"
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
nullorundefinedif the data point is not presented or couldn't be extracted during processing.
Was this page helpful?

