Retrieve Available Sources

Learn about different news publishers available on News API and how to find them.

We'll cover the following

When writing reports on events or issues, we provide citations of the sources we use to support our thesis. For those citations to be significant, they must come from credible sources. That's why it is always important that we know our sources.

The Sources endpoint

Using the Sources endpoint, we can find details about the different sources (news publishers) provided by the News API. This endpoint returns the subset of news publishers that published the top headlines provided by the News API.

The base URL of this endpoint is https://newsapi.org/v2/top-headlines/sources.

Request parameters

The table below contains the query parameters that we can use with the Sources endpoint:

Parameter

Type

Category

Description

apiKey

String

Mandatory

This is the API key.

category

String

Optional

This helps us find sources that display news of a specific category. By default, the user will get sources for all categories in the result.

language

String

Optional

This is used to find sources that display news in a specific language. The possible options are listed in the appendix.

country

String

Optional

This query parameter finds sources from a specific country. The possible options are listed in the appendix.

Using the code widget below, we'll call the Sources endpoint without any query parameters to get all the available sources. Click the "Run" button below to see the response.

Press + to interact
// Define endpoint URL here
const endpointUrl = new URL("https://newsapi.org/v2/top-headlines/sources");
const headerParameters = {
    contentType: "application/json",
};
// Define Query Parameters here
const queryParameters = new URLSearchParams({
    apiKey: '{{API_KEY}}',
});
// Setting API call options
const options = {
    method: "GET",
    headers: headerParameters,
};
// Function to make API call
async function getSources() {
    try {
        endpointUrl.search = queryParameters;
        const response = await fetch(endpointUrl, options);
        
        // Printing response
        printResponse(response);
    } catch (error) {
        // Printing error message
        printError(error);
    }
}
// Calling function to make API call
getSources();

In the above code widget:

  • Line 2: We define the endpoint URL in the endpointUrl variable.

  • Lines 9–11: We assign apiKey in the queryParameters variable because it's a mandatory parameter for the Sources endpoint.

  • Line 23: We use the fetch function to make an API call.

Response fields

Some important response fields of the Sources endpoint are listed in the table below:

Name

Type

Description

status

String

This is the status of the request. If the request is successful, its value is ok. Otherwise, it’s error. In case of an unsuccessful request, code and message are also populated.

sources

Object[array]

This array contains information about the retrieved sources.

id

String

This is the ID of the news source.

name

String

This is the name of the news source.

description

String

This is the description of the news source.

url

String

This is the URL to news source's homepage.

category

String

This is the kind of news to anticipate from this source.

language

String

This the the language that this news source writes in.

country

String

This is the country where this news organization is based (and primarily writes about).

Examples

Let’s look at a few use cases of the Sources endpoint.

Sources for sports

We can find out which sources published articles in the sports category by using the Sources endpoint in the widget provided below. Click the "Run" button to see the response.

Press + to interact
const API_KEY = '{{API_KEY}}';
const endpointUrl = new URL("https://newsapi.org/v2/top-headlines/sources");
const queryParameters = new URLSearchParams({
    apiKey: API_KEY,
    category: 'sports',
});
const headerParameters = {
    contentType: "application/json",
};
const options = {
  method: 'GET',
  headers: headerParameters
};
async function fetchSources() {
  try {
    endpointUrl.search = queryParameters;
    const response = await fetch(endpointUrl, options); 
    printResponse(response); 
  } 
  catch (error) {
    printError(error);
  }
}
fetchSources();

In the above code widget:

  • Line 3: We assign the base URL of Sources endpoint to the endpointUrl variable.

  • Lines 5–8: The queryParameters variable is given request parameters with the following constraints:

    • The category query parameter is set to sports to get sports sources.

  • Line 22: We use the fetch function to call the API endpoint.

Sources in the United States

Using the widget below, we’ll search for sources that are based in the United States. Click the "Run" button below to see the response.

Press + to interact
const API_KEY = '{{API_KEY}}';
const endpointUrl = new URL("https://newsapi.org/v2/top-headlines/sources");
const queryParameters = new URLSearchParams({
    apiKey: API_KEY,
    country: 'us',
});
const headerParameters = {
    contentType: "application/json",
};
const options = {
  method: 'GET',
  headers: headerParameters
};
async function fetchSources() {
  try {
    endpointUrl.search = queryParameters;
    const response = await fetch(endpointUrl, options); 
    printResponse(response); 
  } 
  catch (error) {
    printError(error);
  }
}
fetchSources();

In the above code widget:

  • Line 3: We assign the base URL of the Sources endpoint to the endpointUrl variable.

  • Lines 5–8: We set the country to us in the queryParameters in order to find sources whose country is the United States.

  • Line 22: We give the endpointUrl and options as input parameters to the fetch function to make the API call.