Pagination

The News API provides pagination support for all of its endpoints that return multiple items. Pagination enables you to retrieve large sets of data in smaller, more manageable chunks, reducing the amount of time and bandwidth required to process the data.

Pagination Parameters

The following parameters are used to control pagination:

• page number default: 1
  The page number of the results to retrieve. Each page contains a fixed number of items.
• page_size number default: 20
  The number of items to return per page. The maximum value is 100.

Example

To retrieve the first 20 articles from the News API, you would use the following endpoint:

curl -X GET
  'https://api.example.com/v2/articles?q=tech?page=1&pageSize=20'
  -H 'Authorization: Bearer YOUR_API_KEY'

And here is the response

{
  "status": "ok",
  "total_results": 100,
  "total_pages": 5,
  "page": 1,
  "page_size": 20,
  "articles": [
    {
      "title": "Example article 1",
      "description": "This is an example article.",
      "url": "https://example.com/article1",
      "published_at": "2023-04-10T12:34:56Z",
      "source": {
        "id": "example",
        "name": "Example News"
      }
    },
    {
      "title": "Example article 2",
      "description": "This is another example article.",
      "url": "https://example.com/article2",
      "published_at": "2023-04-09T12:34:56Z",
      "source": {
        "id": "example",
        "name": "Example News"
      }
    },
    ...
  ]
}

Error Handling

If an error occurs during pagination, the News API will return an error response object with an appropriate status code and message. Common errors include:

1. Invalid pagination parameters (e.g., page or page_size is not a positive integer)
2. Requested page is out of range (i.e., greater than total_pages)
3. Internal server error

{
  "status": 400,
  "code": "BAD_REQUEST",
  "message": "Your request is invalid. Check the API documentation for the correct parameters and format."
}

Read more about error handling here Error Handling guide.

How to Implement Pagination

To implement pagination, you need to make use of the page and pageSize query parameters.

• page number default: 1
  This parameter specifies the page number that you want to retrieve. For example, if you want to retrieve the second page of results, you would set the page parameter to 2.
• page_size number default: 20
  This parameter specifies the number of results that you want to retrieve per page. For example, if you want to retrieve 10 results per page, you would set the pageSize parameter to 10.

Here is an example API call that retrieves the second page of news articles with 10 results per page:

curl -X GET
  'https://api.example.com/v2/articles?q=tech?page=2&pageSize=10'
  -H 'Authorization: Bearer YOUR_API_KEY'

Handling Pagination Response

When you make a request with pagination parameters, the API will respond with a JSON object containing the requested page of results, as well as some additional information about the total number of results and the current page.

Here is an example response object:

{
  "articles": [
    // Array of articles
  ],
  "page": 2,
  "pageSize": 10,
  "totalResults": 50
}

• articles array
  An array of articles that were retrieved for the requested page.
• page number
  The current page number.
• pageSize number
  The number of articles returned per page.
• totalResults number
  The total number of articles that match the request, regardless of the number of pages.

Handling Edge Cases

When implementing pagination, there are some edge cases that you should be aware of:

1. When the page parameter is greater than the total number of pages, the API should respond with an empty articles array.
2. When the pageSize parameter is set to 0, the API should respond with an error message indicating that the pageSize parameter cannot be zero.
3. When the pageSize parameter is greater than the maximum allowed page size, the API should respond with an error message indicating that the pageSize parameter exceeds the maximum allowed value