Introduction

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

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 in the Errors section.

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

Endpoints

The API consists of two parts Search API and Monitoring API. Each uses HTTP requests to receive input parameters and send responses.

To send responses of reasonable size, Search API uses Paging, the parameters page and size are used to show different part of search results. All parameters, except the API_KEY are optional, and may be omitted.

The Search API contains following endpoints:

  • News api.datanews.io/v1/news - returns search results over whole index.
  • Headlines api.datanews.io/v1/headlines - returns news headlines.
  • Sources api.datanews.io/v1/sources - returns directly available sources.

The Monitoring API consists of the following endpoints:

  • Create monitor api.datanews.io/v1/monitors/create - create new monitor
  • List monitors api.datanews.io/v1/monitors/list - list all monitors
  • Get by id api.datanews.io/v1/monitors/list/{id} - retrieve monitor by id
  • Delete monitor api.datanews.io/v1/monitors/delete/{id} - delete monitor by id
  • Get monitoring results api.datanews.io/v1/monitors/latest/{run_id} - retrieve monitor run by run_id

You can read more about Monitoring API at the monitoring overview section.

Examples

You can find API query examples on the examples page.

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.

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.

Jump to