Documentation

Guides and reference materials to help you get started, integrate, optimize and troubleshoot your use of the Newsdata.io Platform.

Introduction

This is the documentation page intended to demonstrate various API endpoints that you can use and the parameters that are available when calling them. Different API endpoints are grouped by topic in the left side menu. For most endpoints, you can also check multiple code examples that demonstrate its use using your preferred programming language.

Authentication

The NewsData.io API uses API keys to authenticate requests. Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.

To obtain an API key you have to create an account. You get a free API key while you are in development. When making REST API requests, your API key has to be provided as a parameter in the URL (e.g. apikey=YOUR_API_KEY).

HTTP Response Code

These error codes are produced on their given conditions

200 = Successful operation
400 = Parameter missing
401 = Unauthorized
403 = CORS policy failed. IP/Domain restricted
409 = Parameter duplicate
415 = Unsupported type
422 = Unprocessable entity
429 = Too many requests
500 = Internal server error

Get Latest News

The latest news endpoint provides access to the latest and breaking news for a country, for a specific category in a country, or for a single or multiple domains. The news articles are sorted by the publish date.

Retrieving the latest news allows you to build experience such as showcasing the latest news, breaking news tickers and analyzing News to better understand their content.

Request Parameters

apikey
required
string
Your Newsdata.io API Key. Alternatively you can provide this via the X-ACCESS-KEY HTTP header.
country string
A comma separated string of 2-letter ISO 3166-1 countries (maximum 5) to restrict the search to. Possible Options: us gb in jp ae sa au ca sg
API URL: https://newsdata.io/api/1/news?apikey=YOUR_API_KEY&country=au,ca
category string
A comma separated string of categories (maximum 5) to restrict the search to. Possible Options: top business science technology sports health entertainment
API URL: https://newsdata.io/api/1/news?apikey=YOUR_API_KEY&category=sports,health
language string
A comma separated string of languages (maximum 5) to restrict the search to. Possible Options: en ar jp in es fr
API URL: https://newsdata.io/api/1/news?apikey=YOUR_API_KEY&language=fr,en
domain string
A comma separated string of domains (maximum 5) to restrict the search to. Use the /domains endpoint to find top sources id.
API URL: https://newsdata.io/api/1/news?apikey=YOUR_API_KEY&domain=ctvnews_london
q string
Keywords or phrases to search for in the news title and content. The value must be URL-encoded
Advance search options:
  • Search Social.
    API URL:https://newsdata.io/api/1/news?apikey=YOUR_API_KEY&q=social
  • Search "Social Pizza".
    API URL: https://newsdata.io/api/1/news?apikey=YOUR_API_KEY&q=social%20pizza
  • Search Social but not with pizza. social -pizza
    API URL: https://newsdata.io/api/1/news?apikey=YOUR_API_KEY&q=social%20-pizza
  • Search Social but not with pizza and wildfire. social -pizza -wildfire
    API URL: https://newsdata.io/api/1/news?apikey=YOUR_API_KEY&q=social%20-pizza%20-wildfire
  • Search multiple keyword with AND operator. Search pizza and Social. social AND pizza
    API URL: https://newsdata.io/api/1/news?apikey=YOUR_API_KEY&q=social%20AND%20pizza
  • Search multiple keywords with multiple AND operator. Search pizza and Social and pasta. social AND pizza AND pasta
    API URL: https://newsdata.io/api/1/news?apikey=YOUR_API_KEY&q=social%20AND%20pizza%20AND%20pasta
  • Search multiple keyword with OR operator. Search pizza or Social. pizaa OR social
    API URL: https://newsdata.io/api/1/news?apikey=YOUR_API_KEY&q=social%20OR%20pizza
  • Search pizza or Social but not pasta. pizza OR social -pasta
    API URL: https://newsdata.io/api/1/news?apikey=YOUR_API_KEY&q=social%20OR%20pizza%20-pasta
  • Search multiple keyword with multiple OR operator. Search pizza or Social or pasta. social OR pizza OR pasta
    API URL: https://newsdata.io/api/1/news?apikey=YOUR_API_KEY&q=social%20OR%20pizza%20OR%20pasta

Please note: You can't use AND and OR in the same query.

qInTitle string
Keywords or phrases to search for in the news title only.

Please note: This parameter can't be used with q parameter in the same query.
page int
Use this to page through the results if the total results found is greater than the page size.
Sample Response

Response Object

status string
Status shows the status of your request. If the request was successful then it shows success, in case of error it shows error. In the case of error a code and message property will be displayed.
totalResults int
The total number of results available for your request.
results array
The results of the request
title string
Title of the article.
link string
The direct URL to the article.
source_id string
The id of the source this article came from.
keywords array
The list of keywords related to the article
creator array
The author(s) of the article.
image_url string
Relevant image url for the article.
video_url string
Relevant video url for the article.
description string
A description of the article.
pubDate string
The article publish date and time in UTC.
content string
A Full Content if available of the article.
nextPage int
page parameter value for next request.
SUCCESS
Sample Response
ERROR
Sample Response

News Archive

The news archive endpoint provides access to the old news data for a country, for a specific category in a country, or for a single or multiple domains.

Retrieving a piece of old news allows you to get the past news data for research and analysis purposes.

Request Parameters

apikey
required
string
Your Newsdata.io API Key. Alternatively you can provide this via the X-ACCESS-KEY HTTP header.
country string
A comma separated string of 2-letter ISO 3166-1 countries (maximum 5) to restrict the search to. Possible Options: us gb in jp ae sa au ca sg
API URL: https://newsdata.io/api/1/news?apikey=YOUR_API_KEY&country=au,jp
category string
A comma separated string of categories (maximum 5) to restrict the search to. Possible Options: top business science technology sports health entertainment
API URL: https://newsdata.io/api/1/news?apikey=YOUR_API_KEY&category=sports,top
language string
A comma separated string of languages (maximum 5) to restrict the search to. Possible Options: en ar jp in es fr
API URL: https://newsdata.io/api/1/news?apikey=YOUR_API_KEY&language=fr,es
domain string
A comma separated string of domains (maximum 5) to restrict the search to. Use the /domains endpoint to find top sources id.
API URL: https://newsdata.io/api/1/news?apikey=YOUR_API_KEY&domain=ctvnews_london
from_date string
A date and optional time for the oldest article allowed. This should be in ISO 8601 format (e.g. 2021-04-18 or 2021-04-18T04:04:34)
API URL: https://newsdata.io/api/1/news?apikey=YOUR_API_KEY&from_date=2021-04-18
to_date string
A date and optional time for the newest article allowed. This should be in ISO 8601 format (e.g. 2021-04-18 or 2021-04-18T04:04:34)
API URL: https://newsdata.io/api/1/news?apikey=YOUR_API_KEY&to_date=2021-04-18
q string
Keywords or phrases to search for in the news title and content. The value must be URL-encoded
Advance search options:
  • Search Social.
    API URL:https://newsdata.io/api/1/archive?apikey=YOUR_API_KEY&q=social
  • Search "Social Pizza".
    API URL: https://newsdata.io/api/1/archive?apikey=YOUR_API_KEY&q=social%20pizza
  • Search Social but not with pizza. social -pizza
    API URL: https://newsdata.io/api/1/archive?apikey=YOUR_API_KEY&q=social%20-pizza
  • Search Social but not with pizza and wildfire. social -pizza -wildfire
    API URL: https://newsdata.io/api/1/archive?apikey=YOUR_API_KEY&q=social%20-pizza%20-wildfire
  • Search multiple keyword with AND operator. Search pizza and Social. social AND pizza
    API URL: https://newsdata.io/api/1/archive?apikey=YOUR_API_KEY&q=social%20AND%20pizza
  • Search multiple keywords with multiple AND operator. Search pizza and Social and pasta. social AND pizza AND pasta
    API URL: https://newsdata.io/api/1/archive?apikey=YOUR_API_KEY&q=social%20AND%20pizza%20AND%20pasta
  • Search multiple keyword with OR operator. Search pizza or Social. pizaa OR social
    API URL: https://newsdata.io/api/1/archive?apikey=YOUR_API_KEY&q=social%20OR%20pizza
  • Search pizza or Social but not pasta. pizza OR social -pasta
    API URL: https://newsdata.io/api/1/archive?apikey=YOUR_API_KEY&q=social%20OR%20pizza%20-pasta
  • Search multiple keyword with multiple OR operator. Search pizza or Social or pasta. social OR pizza OR pasta
    API URL: https://newsdata.io/api/1/archive?apikey=YOUR_API_KEY&q=social%20OR%20pizza%20OR%20pasta

Please note: You can't use AND and OR in the same query.

qInTitle string
Keywords or phrases to search for in the news title only.

Please note: This parameter can't be used with q parameter in the same query.
page int
Use this to page through the results if the total results found is greater than the page size.
Sample Response

Response Object

status string
Status shows the status of your request. If the request was successful then it shows success, in case of error it shows error. In the case of error a code and message property will be displayed.
totalResults int
The total number of results available for your request.
results array
The results of the request
title string
Title of the article.
link string
The direct URL to the article.
source_id string
The id of the source this article came from.
keywords array
The list of keywords related to the article
creator array
The author(s) of the article.
image_url string
Relevant image url for the article.
video_url string
Relevant video url for the article.
description string
A description of the article.
pubDate string
The article publish date and time in UTC.
content string
A Full Content if available of the article.
nextPage int
page parameter value for next request.
SUCCESS
Sample Response
ERROR
Sample Response

News Sources

News sources endpoint provides access to the subsets of news publishers that the latest news is available from.

It's mainly a convenience endpoint that you can use to keep track of the publishers available on the API, and you can pipe it straight through to your users

Request Parameters

apikey
required
string
Your Newsdata.io API Key. Alternatively you can provide this via the X-ACCESS-KEY HTTP header.
country string
Find sources that display news in a specific country. Possible Options: us gb in jp ae sa au ca sg
API URL: https://newsdata.io/api/1/news?apikey=YOUR_API_KEY&country=jp,ae
category string
Find sources that display news of this category. Possible Options: top business science technology sports health entertainment
API URL: https://newsdata.io/api/1/news?apikey=YOUR_API_KEY&tcategory=sports,top
language string
Find sources that display news in a specific language. Possible Options: en ar jp in es fr
API URL: https://newsdata.io/api/1/news?apikey=YOUR_API_KEY&language=en,ar
Sample Response

Response Object

status string
Status shows the status of your request. If the request was successful then it shows success, in case of error it shows error. In the case of error a code and message property will be displayed.
results array
The results of the request
id string
The identifier of the news source. You can use this with our other endpoints.
name string
The name of the news source.
url string
The URL of the homepage.
category string
The type of news to expect from this news source.
language string
The language that this news source writes in.
country string
The country this news source is based in (and primarily writes about).
SUCCESS
Sample Response
ERROR
Sample Response