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.
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.
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:
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.
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:
api.datanews.io/v1/news
- returns search results over whole index.api.datanews.io/v1/headlines
- returns news headlines.api.datanews.io/v1/sources
- returns directly available sources.The Monitoring API consists of the following endpoints:
api.datanews.io/v1/monitors/create
- create new monitorapi.datanews.io/v1/monitors/list
- list all monitorsapi.datanews.io/v1/monitors/list/{id}
- retrieve monitor by idapi.datanews.io/v1/monitors/delete/{id}
- delete monitor by idapi.datanews.io/v1/monitors/latest/{run_id}
- retrieve monitor run by run_idYou can read more about Monitoring API at the monitoring overview section.
You can find API query examples on the examples page.
Datanews uses HTTP status codes to indicate success or failure of the API request.
General summary:
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. |
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.