Article endpoint

The Articles endpoint allows you to retrieve articles from a specific source, category, or query. You can specify the number of results to return and sort the results by different criteria.

Endpoint URL

GET /articles

Query Parameters

The following parameters can be used to filter the articles:

• q string required
  Search keyword(s)
• sources string
  A comma-separated string of news source ids.
• domains string
  A comma-separated string of domains to restrict the search to.
• excludeDomains string
  A comma-separated string of domains to exclude from the search.
• from string
  A date and optional time for the oldest article allowed. (format: "yyyy-MM-dd'T'HH:mm:ss'Z'")
• to string
  A date and optional time for the newest article allowed. (format: "yyyy-MM-dd'T'HH:mm:ss'Z'")
• language string
  The language to restrict the articles to.
• sortBy string
  The order to sort the articles in. Possible values are relevancy, popularity, and publishedAt.
• page number default: 20
  Use this to page through the results.
• pageSize number default: 20
  The number of results to return per page.

Example

curl -X GET
  'https://api.example.com/v2/articles?q=trump&sources=cnn'
  -H 'Authorization: Bearer YOUR_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 Articles 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. Want to learn how to query available sources? Sources endpoint
2. Handle error properly. Error handling guide