API Features
Live News
The full set of available real-time news articles can be accessed using a simple API request to the mediastack API's news endpoint. Below you will find an example API request as well as a series of optional parameters you can use to filter your news results.
Delayed news on Free Plan: Please note that account subscribed to the Free Plan will receive live news only with a 30-minute delay. To lift this limitation and get news in real-time, please sign up or upgrade to the Standard Plan or higher.
Example API Request:
Sign Up to Run API Request
HTTP GET Request Parameters:
| Object | Description |
|---|---|
access_key | [Required] Use this parameter to specify your unique API access key, which is shown when you log in to your account dashboard. |
sources | [Optional] Use this parameter to include or exclude one or multiple comma-separated news sources. Example: To include CNN, but exclude BBC: &sources=cnn,-bbc |
categories | [Optional] Use this parameter to include or exclude one or multiple comma-separated news categories. Example: To include business, but exclude sports: Supported Categories
|
countries | [Optional] Use this parameter to include or exclude one or multiple comma-separated countries. Example: To include Australia, but exclude the US: &countries=au,-us.Available countries: See all supported countries |
languages | [Optional] Use this parameter to include or exclude one or multiple comma-separated languages. Example: To include English, but exclude German: Supported Languages
|
keywords | [Optional] Use this parameter to seach for sentences, you can also exclude words that you do not want to appear in your search results. Example: To search for "New movies 2021" but exclude "Matrix": &keywords=new movies 2021 -matrix |
date | [Optional] Use this parameter to specify a date or date range. Example: &date=2020-01-01 for news on Jan 1st and &date=2020-12-24,2020-12-31 for news between Dec 24th and 31st. |
sort | [Optional] Use this parameter to specify a sorting order. Available values: published_desc (default), published_asc, popularity |
limit | [Optional] Use this parameter to specify a pagination limit (number of results per page) for your API request. Default limit value is 25, maximum allowed limit value is 100. |
offset | [Optional] Use this parameter to specify a pagination offset value for your API request. Example: An offset value of 100 combined with a limit value of 10 would show results 100-110. Default value is 0, starting with the first available result. |
Example API Response:
If your API request has been successful, the mediastack API will return HTTP status 200 together with a JSON result, carrying a pagination object as well as a data object containing one or multiple news articles.
API Response Objects:
| Response Object | Description |
|---|---|
pagination > limit | Returns your pagination limit value. |
pagination > offset | Returns your pagination offset value. |
pagination > count | Returns the results count on the current page. |
pagination > total | Returns the total count of results available. |
data > author | Returns the name of the author of the given news article. |
data > title | Returns the title text of the given news article. |
data > description | Returns the description text of the given news article. |
data > url | Returns the URL leading to the given news article. |
data > image | Returns an image URL associated with the given news article. |
data > category | Returns the category associated with the given news article. |
data > language | Returns the language the given news article is in. |
data > country | Returns the country code associated with the given news article. |
data > published_at | Returns the exact time stamp the given news article was published. |
Empty Data: Please note that if no results are found for your specific query, the
dataobject will contain no results.
Historical News
If you are subscribed to the Standard Plan or higher, you will be able to access historical news data by specifying a historical date using the API's date parameter in YYYY-MM-DD format. Find an example request below.
Example API Request:
Sign Up to Run API Request
HTTP GET Request Parameters:
| Object | Description |
|---|---|
access_key | [Required] Use this parameter to specify your unique API access key, which is shown when you log in to your account dashboard. |
date | [Required] Use this parameter to specify your historical date or date range. Example: &date=2020-01-01 for news on Jan 1st and &date=2020-12-24,2020-12-31 for news between Dec 24th and 31st. |
sources | [Optional] Use this parameter to include or exclude one or multiple comma-separated news sources. Example: To include CNN, but exclude BBC: &sources=cnn,-bbc |
categories | [Optional] Use this parameter to include or exclude one or multiple comma-separated news categories. Example: To include business, but exclude sports: Supported Categories
|
countries | [Optional] Use this parameter to include or exclude one or multiple comma-separated news categories. Example: To include Australia, but exclude the US: &countries=au,-us.Available countries: See all supported countries |
languages | [Optional] Use this parameter to include or exclude one or multiple comma-separated languages. Example: To include English, but exclude German:
Supported Languages
|
keywords | [Optional] Use this parameter to include or exclude one or multiple comma-separated search keywords. Example: To include the keyword "virus", but exclude "corona": &keywords=virus,-corona |
sort | [Optional] Use this parameter to specify a sorting order. Available values: published_desc (default), published_asc, popularity |
limit | [Optional] Use this parameter to specify a pagination limit (number of results per page) for your API request. Default limit value is 25, maximum allowed limit value is 100. |
offset | [Optional] Use this parameter to specify a pagination offset value for your API request. Example: An offset value of 100 combined with a limit value of 10 would show results 100-110. Default value is 0, starting with the first available result. |
Example API Response:
API Response Objects:
| Response Object | Description |
|---|---|
pagination > limit | Returns your pagination limit value. |
pagination > offset | Returns your pagination offset value. |
pagination > count | Returns the results count on the current page. |
pagination > total | Returns the total count of results available. |
data > author | Returns the name of the author of the given news article. |
data > title | Returns the title text of the given news article. |
data > description | Returns the description text of the given news article. |
data > url | Returns the URL leading to the given news article. |
data > image | Returns an image URL associated with the given news article. |
data > category | Returns the category associated with the given news article. |
data > language | Returns the language the given news article is in. |
data > country | Returns the country code associated with the given news article. |
data > published_at | Returns the exact time stamp the given news article was published. |
News Sources
Using the sources endpoint together with a series of search and filter parameters you will be able to search all news sources supported by the mediastack API. The API will return all source metadata available, including the source ID required to define sources when requesting live or historical news.
Example API Request:
Sign Up to Run API Request
HTTP GET Request Parameters:
| Object | Description |
|---|---|
access_key | [Required] Use this parameter to specify your unique API access key, which is shown when you log in to your account dashboard. |
search | [Required] Use this parameter to specify one or multiple search keywords. |
countries | [Optional] Use this parameter to include or exclude one or multiple comma-separated countries. Available countries: See all supported countries |
languages | [Optional] Use this parameter to include or exclude one or multiple comma-separated languages.
Supported Languages
|
categories | [Optional] Use this parameter to include or exclude one or multiple comma-separated news categories.
Supported Categories
|
limit | [Optional] Use this parameter to specify a pagination limit (number of results per page) for your API request. Default limit value is 25, maximum allowed limit value is 100. |
offset | [Optional] Use this parameter to specify a pagination offset value for your API request. Example: An offset value of 100 combined with a limit value of 10 would show results 100-110. Default value is 0, starting with the first available result. |
Example API Response:
API Response Objects:
| Response Object | Description |
|---|---|
pagination > limit | Returns your pagination limit value. |
pagination > offset | Returns your pagination offset value. |
pagination > count | Returns the results count on the current page. |
pagination > total | Returns the total count of results available. |
data > id | Returns the source ID of the given news source. This is also the ID you need to pass to the API's sources parameter when requesting live or historical news data. |
data > name | Returns the name of the given news source. |
data > category | Returns the category associated with the given news source. |
data > country | Returns the country associated with the given news source. |
data > language | Returns the language associated with the given news source. |
data > url | Returns a URL leading to the given news source. |