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.
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:
apiKey=API_KEY query string parameterAuthorization: Bearer API_KEY headerx-api-key: API_KEY headerAll 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.
We recommend using second or third methods of providing API key, because they prevent the API key from being shown in the query string.
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. |
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.
You can retrieve recent headlines with api.datanews.io/v1/headlines endpoint.
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. |
You can search over whole news index using api.datanews.io/v1/news endpoint.
| # | 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. |
You can see monitored sources using api.datanews.io/v1/sources endpoint.
| # | 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. |
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 \+.
To find an exact match of the phrase, you could wrap it into double quotes, e.g. "YOUR PHRASE" construct.
See an example below.
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 groupingRequests 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.