Sources Endpoint

The Sources Endpoint provides a way to retrieve information about news sources available on the API.

Endpoint

GET /sources

Query Parameters

The following parameters can be used to filter the sources:

• category string
  The category of the news sources. Possible values are business, entertainment, general, health, science, sports, and technology.
• language string
  The language of the news sources. Possible values are AR, DE, EN, ES, FR, HE, IT, NL, NO, PT, RU, SE, and UD.
• country string
  The country of the news sources. Possible values are AE, AR, AT, AU, BE, BG, BR, CA, CH, CN, CO, CU, CZ, DE, EG, FR, GB, GR, HK, HU, ID, IE, IL, IN, IT, JP, KR, LT, LV, MA, MX, MY, NG, NL, NO, NZ, PH, PL, PT, RO, RS, RU, SA, SE, SG, SI, SK, TH, TR, TW, UA, US, VE, ZA.

Example

curl -X GET
  'https://api.example.com/v2/sources'
  -H 'Authorization: Bearer API_KEY'

Response

The response will be an array of news sources that match the given parameters. Each source has the following fields:

• id string
  The unique id of the news source.
• name string
  The name of the news source.
• description string
  A description of the news source.
• url string
  The URL of the news source.
• category string
  The category of the news source.
• language string
  The language of the news source.
• country string
  The country of the news source

Here's an example response:

{
  "status": "ok",
  "page": 1,
  "pageSize": 10,
  "sources": [
    {
      "id": "abc-news",
      "name": "ABC News",
      "description": "Your trusted source for breaking news, analysis, exclusive interviews, headlines, and videos at ABCNews.com.",
      "url": "https://abcnews.go.com",
      "category": "general",
      "language": "en",
      "country": "us"
    },
    {
      "id": "al-jazeera-english",
      "name": "Al Jazeera English",
      "description": "News, analysis from the Middle East and worldwide, multimedia and interactives, opinions, documentaries, podcasts, long reads and broadcast schedule.",
      "url": "https://www.aljazeera.com",
      "category": "general",
      "language": "en",
      "country": "us"
    },
    // ...
  ]
}

Rate Limiting

The API limits the number of requests per minute per API key to prevent abuse. If you exceed the rate limit, you'll receive a 429 TOO_MANY_REQUESTS response.

Authentication

To authenticate your requests, you must include your API key in the Authorization header of your HTTP requests. The API key can be obtained from the developer portal.

The header should be in the following format:

Authorization: Bearer API_KEY

Replace API_KEY with your actual API key.

Error Responses

If there's an error with your request, the API will return an error response in JSON format with a status property of error and an errorMessage property with a message describing the error. Here's an example error response:

{
  "status": 400,
  "errorMessage": "Invalid country code",
  "errorCode": "INVALID_COUNTRY_CODE",
}

Read more about error handling here Error Handling guide.

Pagination

The Sources endpoint supports pagination to retrieve more than the default number of results. The response will include a totalResults property indicating the total number of results available for the specified query parameters. The page and pageSize query parameters can be used to retrieve specific pages of results.

The default pageSize value is 20, and the maximum value is 100.

Usage Limits

The API usage limits are subject to change at any time without notice. It's your responsibility to ensure that your application complies with the usage limits and doesn't abuse the service.

If you need to increase your usage limits, please contact us at support@example.com.

What's next

1. Handle error properly. Error handling guide