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.

Quick start

The easiest way to start using the API is to install our client library, or to make requests using curl or any other command line utility, see examples page. Your API key will be included in all of the examples, if you are signed in.

Install the library with command:

pip install datanews

Use your API key to initialize it. You can find the API key on top of this page, or in the Account Settings.

Here is a sample code that will query recent headlines in english about 'SpaceX'.

import datanews
datanews.api_key = 'API_KEY'

response = datanews.headlines(q='SpaceX', language=['en'])
articles = response['hits']
print(articles[0]['title'])

You can find more examples of queries on the Examples page. Advanced queries page covers how to build more advanced queries with special query language, including searching for exact matches, word combinations and other.

You can read more information about Authentication, Endpoints and Errors below. Use the navigation bar to simplify the search.

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.

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.

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.