Querying

guides

The News API provides a number of query options that can be used to filter and search for news articles. This guide provides an overview of these query options.

Query Parameters

The following query parameters can be used to filter the news articles:

q
Search query term or phrase. Eg: trump, bitcoin.
sources
A comma-separated string of news source ids. Eg: bbc-news, cnn, ign.
domains
A comma-separated string of domains to restrict the search to. Eg: nytimes.com, wsj.com.
excludeDomains
A comma-separated string of domains to exclude from the search. Eg: nytimes.com, wsj.com.
from
A date and optional time for the oldest article allowed. Eg: 2021-04-10 or 2021-04-10T08:30:00.
to
A date and optional time for the newest article allowed. Eg: 2021-04-12 or 2021-04-12T08:30:00.
language
The 2-letter ISO-639-1 code of the language in which the articles should be returned. Eg: EN, ES, DE.
sortBy
The order to sort the articles in. Possible values are relevancy, popularity, and publishedAt.
pageSize
The number of results to return per page. Maximum is 100.
page
Use this to page through the results if the total results found is greater than the page size.

Ideally you want to reduce the number of queries and increase the pageSize for optimal usage.

Example Usage

Here is an example of a query to search for news articles about "technology" from the sources "bbc-news" and "cnn", sorted by relevance, and limited to the first 5 results:

Request

curl -X GET
  'https://api.example.com/v2/articles?q=technology&sources=bbc-news,cnn&sortBy=relevancy&pageSize=5'
  -H 'Authorization: Bearer YOUR_API_KEY'

Here's an example response:

Response

{
  "status": "ok",
  "totalResults": 5,
  "articles": [
    {
      "source": {
        "id": "cnn",
        "name": "CNN"
      },
      "author": "John Smith",
      "title": "New Study Shows Benefits of Exercise on Mental Health",
      "description": "A new study conducted by leading experts in the field has found that regular exercise can have significant positive effects on mental health.",
      "url": "https://www.cnn.com/health/exercise-mental-health-study",
      "urlToImage": "https://cdn.cnn.com/cnnnext/dam/assets/210302162053-exercise-walking-gettyimages-1212151885-super-tease.jpg",
      "publishedAt": "2023-04-10T08:00:00Z",
      "content": "The study followed 1,000 participants over the course of a year and found that those who engaged in regular exercise experienced lower rates of depression and anxiety, as well as improved cognitive function and overall well-being. The results were consistent across all age groups and fitness levels."
    },
    {
      "source": {
        "id": "bbc-news",
        "name": "BBC News"
      },
      "author": "Jane Doe",
      "title": "New Breakthrough in Nuclear Physics",
      "description": "Scientists have finally found out how to produce energy by nuclear fusion",
      "url": "https://www.bbc.com/news/health/nuclear-fusion-breakthrough",
      "urlToImage": "https://images.unsplash.com/photo-1655635949212-1d8f4f103ea1?ixlib=rb-4.0.3&ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&auto=format&fit=crop&w=928&q=80",
      "publishedAt": "2023-04-10T07:30:00Z",
      "content": "The breakthrough involves use of new technologies that would power the future of humanity"
    },
    // more articles...
  ]
}

What's next

Get latest news headlines. Latest Headlines endpoint
Query articles based on filters? Articles endpoint

Was this page useful?

Quickstart

Pagination