Introduction Last updated: 2020-05-02

Datanews API is an HTTP REST API for retrieving recent news articles. Our API accepts HTTP GET requests, and returns JSON-encoded responses. It uses standard HTTP response codes to indicate request's response status. To use the API you must obtain an API key, see Authentication section. There are two main endpoints, one retrieving current news headlines, another for searching over all indexed articles.

Authentication

Datanews uses API keys to authenticate requests.

You can obtain an API key by registering on the website. The API keys grant access to the API resources, therefore you should keep them secure. Do not share them with anyone. If you have registered you can find your personal API key here.

You can pass the API key in the HTTP request in following ways:

  • as the apiKey=API_KEY query string parameter
  • as the Authorization: Bearer API_KEY header
  • as the x-api-key: API_KEY header

All requests will be handled via HTTPS. Requests that do not have an API key, or have an invalid API key would result in an error. You can find possible error codes here.

Warning

We recommend using second or third methods of providing API key, because they prevent the API key from being shown in the query string.

Errors

Datanews uses HTTP status codes to indicate success or failure of the API request.

General summary:

  • Codes 2xx indicate successful request.
  • Codes 4xx indicate an error with error message provided in the response body.
  • Codes 5xx indicate Datanews server errors.

For each response the server returns the status code. Below are all possible response codes from the server.

# Status code Description
1 200 - OK Request succeeded.
2 400 - Bad Request The provided request was invalid.
3 401 - Unauthorized No valid API key provided.
4 403 - Forbidden The account is unconfirmed or is disabled.
5 404 - Not Found The requested resource does not exist.
6 429 - Too Many Requests Too many requests hit the API.
7 500, 502, 503, 504 - Server Errors Datanews backend error.

APIs

The APIs consists of three endpoints. Each uses HTTP GET request to receive input parameters. To send responses of reasonable size, the API uses Paging, the parameters page and size are used to show different part of search results.

Headlines

You can retrieve recent headlines with api.datanews.io/v1/headlines endpoint.

Request
Response

Parameters

The value of passed parameters should be url encoded.

# Parameter Description
1 q Search query, may consist of any number of keywords. See building advanced queries.
2 source Domain name of the source (e.g. economist.com).
3 country Publisher's country. See the list of available countries.
4 language Article language. See the list of supported languages.
5 page Zero-based page index, must not be negative.
6 size Page size, could be 10, 25 or 100.
7 sortBy Sort by relevance or by date.

News Search

You can search over whole news index using api.datanews.io/v1/news endpoint.

Request
Response

Parameters

# Parameter Description
1 q Search query, may consist of any number of keywords.
2 from Search news starting from date, including the date itself. Date format: yyyy-mm-dd.
3 to Search news up to date, including the date itself. Date format: yyyy-mm-dd.
4 source Domain name of the source (e.g. economist.com).
5 country Publisher's country. See the list of available countries.
6 language Article language. See the list of supported languages.
7 page Zero-based page index, must not be negative.
8 size Page size, could be 10, 25 or 100.
9 sortBy Sort by relevance or by date.

Sources

You can see monitored sources using api.datanews.io/v1/sources endpoint.

Request
Response

Parameters

# Parameter Description
1 country Publisher's country. See the list of available countries.
2 language Article language. See the list of supported languages.
3 page Zero-based page index, must not be negative.
4 size Page size, could be 10, 25 or 100.

Advanced search queries

Datanews API has several special functions used for building advanced search queries. By default, provided search keywords will be tokenized as is and then will be used to search the news index. But, if you need to search for an exact phrase, or to find a specific combination of terms using boolean operators, then you could do that too.

These search queries use special symbols (e.g. +, |, -), each has it's own semantic meaning. If you want to search for a phrase that includes, say +, then you have to escape it in the following way \+.

Exact match

To find an exact match of the phrase, you could wrap it into double quotes, e.g. "YOUR PHRASE" construct. See an example below.

Request
Response

Boolean operators

Boolean operators can be used to search for different combination of keywords. Datanews supports following boolean operators:

  • + AND operator
  • | OR operator
  • - NOT operator
  • * operator at the end of term signifies prefix query
  • ( ... ) parentheses for grouping
Request
Response

Rate Limiting

Requests are being rate limited. If the number of requests made exceeds request quota associated with the API key, the request will be rejected. You will have to wait in order to make another request. You can increase your request quota by upgrading your plan.