Latest Headlines Endpoint

Retrieves a list of latest headlines articles from various sources.

Endpoint

GET /latest-headlines

Query Parameters

• country string
  The 2-letter ISO 3166-1 code of the country to get news from.
• category string
  The category of the news to retrieve. Valid values are: business, entertainment, general, health, science, sports, technology.
• page number default: 20
  The number of results to retrieve per page. The maximum value is 100.
• pageSize number default: 20
  The number of results to return per page.

Example

curl -X GET
  'https://api.example.com/v2/latest-headlines?country=us&category=health&pageSize=10&page=1'
  -H 'Authorization: Bearer API_KEY'

Response

The response will be an array of articles, where each article object contains the following properties:

• source object
  The news source
  • id string
    The news source id
  • name string
    The news source name. eg: CNN
• author string
  The author of the article.
• title string
  The title of the article.
• description string
  A short description of the article.
• url string
  The URL of the article.
• urlToImage string
  The URL of the image associated with the article.
• publishedAt date
  The date and time when the article was published.
• content string
  The full content of the article.

Here's an example response:

{
  "status": "ok",
  "totalResults": 20,
  "page": 1,
  "pageSize": 10,
  "articles": [
    {
      "source": {
        "id": "cnn",
        "name": "CNN"
      },
      "author": "John Smith",
      "title": "Article title",
      "description": "Article description",
      "url": "https://www.example.com/article",
      "urlToImage": "https://www.example.com/image.jpg",
      "publishedAt": "2023-04-10T14:30:00Z",
      "content": "Article content"
    },
    // ...
  ]
}

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 Top News 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. Query articles based on filters? Articles endpoint
2. Want to learn how to query available sources? Sources endpoint