API Documentation

The mediastack API was built to provide a powerful, scalable yet easy-to-use REST API interface delivering worldwide live and historical news data in handy JSON format. The API comes with a single news HTTP GET endpoint along with a series of parameters and options you can use to narrow down your news data results. Among other options, you can filter by dates and timeframes, countries, langauges, sources and search keywords.

To get started right away, you can either jump to our 3-Step Quickstart Guide using the button above or scroll down and learn how to authenticate with the mediastack API. If you do not have an account yet, please make sure to get a free API key now to start testing the API and retrieve your first news article.

Getting Started

API Authentication

To make an API request, you will need an API access key and authenticate with the API by attaching the access_key GET parameter to the base URL and set it to your unique access key. Find below an example request.

Example API Request:

Sign Up to Run API Requesthttps://api.mediastack.com/v1/news
    ? access_key = YOUR_ACCESS_KEY

A unique API access key is generated for each mediastack account, and it usually never changes. There can only ever be one API access key at a time per account. If you need to re-generate your key, you can do so by logging in to your account dashboard.

Keep your key safe: To avoid abuse of your mediastack account, please keep your API access key safe, do not use it in client-side applications and do not publish it anywhere.

256-bit HTTPS Encryption Available on: Standard Plan and higher

To connect to the mediastack API using 256-bit HTTPS (SSL) encryption, you will need to be subscribed to the Standard Plan or higher. If you are on the Free Plan, please note that you will be limited to HTTP connections.

Example API Request:

https://api.mediastack.com/v1

API Errors

If your API request was unsuccessful, you will receive a JSON error in the format outlined below, carrying code, message and context response objects in order to communicate the type of error that occurred and details to go with it. The API will also return HTTP status codes in accordance with the type of API response sent.

Below you will find an example API error that occurs if an unknown value is set for the API's date parameter.

Example Error:

{
   "error": {
      "code": "validation_error",
      "message": "Validation error",
      "context": {
         "date": [
            "NO_SUCH_CHOICE_ERROR"
         ]
      }
   }
}

Common API Errors:

Type	Description
`invalid_access_key`	An invalid API access key was supplied.
`missing_access_key`	No API access key was supplied.
`inactive_user`	The given user account is inactive.
`https_access_restricted`	HTTPS access is not supported on the current subscription plan.
`function_access_restricted`	The given API endpoint is not supported on the current subscription plan.
`invalid_api_function`	The given API endpoint does not exist.
`404_not_found`	Resource not found.
`usage_limit_reached`	The given user account has reached its monthly allowed request volume.
`rate_limit_reached`	The given user account has reached the rate limit.
`internal_error`	An internal error occurred.

API Features

Live News Available on: All plans

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 Requesthttps://api.mediastack.com/v1/news
    ? access_key = YOUR_ACCESS_KEY
    & keywords = tennis
    & countries = us, gb, de

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: `&sources=business,-sports`. Available categories: View all 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: `&sources=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: `&sources=en,-de`. Available languages: View all 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": `&sources=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.

{
    "pagination": {
        "limit": 100,
        "offset": 0,
        "count": 100,
        "total": 293
    },
    "data": [
        {
            "author": "TMZ Staff",
            "title": "Rafael Nadal Pulls Out Of U.S. Open Over COVID-19 Concerns",
            "description": "Rafael Nadal is officially OUT of the U.S. Open ... the tennis legend said Tuesday it's just too damn unsafe for him to travel to America during the COVID-19 pandemic. \"The situation is very complicated worldwide,\" Nadal wrote in a statement. \"The…",
            "url": "https://www.tmz.com/2020/08/04/rafael-nadal-us-open-tennis-covid-19-concerns/",
            "source": "TMZ.com",
            "image": "https://imagez.tmz.com/image/fa/4by3/2020/08/04/fad55ee236fc4033ba324e941bb8c8b7_md.jpg",
            "category": "general",
            "language": "en",
            "country": "us",
            "published_at": "2020-08-05T05:47:24+00:00"
        },
        [...]
    ]
}

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 data object will contain no results.

Historical News Available on: Standard Plan and higher

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 Requesthttps://api.mediastack.com/v1/news
    ? access_key = YOUR_ACCESS_KEY
    & date = 2020-07-17

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: `&sources=business,-sports`. Available categories: View all 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: `&sources=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: `&sources=en,-de`. Available languages: View all 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": `&sources=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:

{
    "pagination": {
        "limit": 100,
        "offset": 0,
        "count": 100,
        "total": 293
    },
    "data": [
        {
            "author": "CNN Staff",
            "title": "This may be the big winner of the market crash",
            "description": "This may be the big winner of the market crash",
            "url": "http://rss.cnn.com/~r/rss/cnn_topstories/~3/KwE80_jkKo8/a-sa-dd-3",
            "source": "CNN",
            "image": "https://cdn.cnn.com/cnnnext/dam/assets/150325082152-social-gfx-cnn-logo-super-169.jpg",
            "category": "general",
            "language": "en",
            "country": "us",
            "published_at": "2020-07-17T23:35:06+00:00"
        },
        [...]
    ]
}

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 Available on: All plans

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 Requesthttps://api.mediastack.com/v1/sources
    ? access_key = YOUR_ACCESS_KEY
    & search = abc

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. Available languages: View all supported languages
`categories`	[Optional] Use this parameter to include or exclude one or multiple comma-separated news categories. Available categories: View all 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:

{
    "pagination": {
        "limit": 100,
        "offset": 0,
        "count": 100,
        "total": 1364
    },
    "data": [
        {
            "id": "abc-au",
            "name": "ABC AU",
            "category": "general",
            "country": "au",
            "language": "en",
            "url": "http://abc.net.au/"
        },
        [...]
    ]
}

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.

Options & Parameters

Specify Sources Available on: All plans

When making a news data API request, you can filter down your results by news sources. To do that you will need to attach the sources parameter to your API request URL and set it to one or multiple news source values. As you can see in the example below, it is also possible to exclude specific news sources by prepending them with a - symbol.

Example API Request:

Sign Up to Run API Requesthttps://api.mediastack.com/v1/news
    ? access_key = YOUR_ACCESS_KEY
    & sources = cnn,-bbc

Example API Response:

Need to see how an API response looks like? Jump to one of our example API responses above.

Specify Categories Available on: All plans

You can also filter news articles by category. To do this, simply attach the API's categories parameter and set it to one or multiple comma-separated values. As with other parameters, you can also exclude categories by prepending a - symbol.

Available News Categories:

general - Uncategorized News
business - Business News
entertainment - Entertainment News
health - Health News
science - Science News
sports - Sports News
technology - Technology News

Example API Request:

Sign Up to Run API Requesthttps://api.mediastack.com/v1/news
    ? access_key = YOUR_ACCESS_KEY
    & categories = health,-sports

Example API Response:

Need to see how an API response looks like? Jump to one of our example API responses above.

Specify Countries Available on: All plans

You can also filter news articles by country. To do this, simply attach the API's countries parameter and set it to one or multiple comma-separated 2-letter country codes. As with other parameters, you can also exclude countries by prepending a - symbol. You can browse all supported countries here.

Example API Request:

Sign Up to Run API Requesthttps://api.mediastack.com/v1/news
    ? access_key = YOUR_ACCESS_KEY
    & countries = au,-us

Example API Response:

Need to see how an API response looks like? Jump to one of our example API responses above.

Specify Languages Available on: All plans

You can also filter news articles by language. To do this, simply attach the API's languages parameter and set it to one or multiple comma-separated 2-letter language codes. As with other parameters, you can also exclude languages by prepending a - symbol.

Available Languages:

ar - Arabic
de - German
en - English
es - Spanish
fr - French
he - Hebrew
it - Italian
nl - Dutch
no - Norwegian
pt - Portuguese
ru - Russian
se - Swedish
zh - Chinese

Example API Request:

Sign Up to Run API Requesthttps://api.mediastack.com/v1/news
    ? access_key = YOUR_ACCESS_KEY
    & languages = en,-de

Example API Response:

Need to see how an API response looks like? Jump to one of our example API responses above.

Search Keywords Available on: All plans

To narrow down your search for articles even more, you can specify one or multiple comma-separated search keywords. As with other parameters, you can also exclude keywords by prepending a - symbol. Find a few clarifications about this parameter below.

Clarifications:

& keywords = food industry - Search for keyword "food industry"
& keywords = food industry, meat - Search for keywords "food industry" and "meat"
& keywords = food industry, -meat - Search for keywords "food industry", but exclude "meat"
& keywords = -food industry, -meat - Search for all news, excluding "food industry" and "meat"
& keywords = a-plus - Search for keyword "a-plus"
& keywords = a, -plus - Search for keyword "a", but exclude "plus"

Example API Request:

Sign Up to Run API Requesthttps://api.mediastack.com/v1/news
    ? access_key = YOUR_ACCESS_KEY
    & keywords = virus,-corona

Example API Response:

Need to see how an API response looks like? Jump to one of our example API responses above.

Code Examples

The mediastack news API supports any client and server-side programming language. We have prepared code examples for the languages PHP, Python, jQuery, Go and Ruby.

Code Example - PHP

$queryString = http_build_query([
  'access_key' => 'ACCESS_KEY',
  'keywords' => 'Wall street -wolf', // the word "wolf" will be
  'categories' => '-entertainment',
  'sort' => 'popularity',
]);

$ch = curl_init(sprintf('%s?%s', 'https://api.mediastack.com/v1/news', $queryString));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$json = curl_exec($ch);

curl_close($ch);

$apiResult = json_decode($json, true);

print_r($apiResult);

Code Example - Python

# Python 3
import http.client, urllib.parse

conn = http.client.HTTPConnection('api.mediastack.com')

params = urllib.parse.urlencode({
    'access_key': 'ACCESS_KEY',
    'categories': '-general,-sports',
    'sort': 'published_desc',
    'limit': 10,
    })

conn.request('GET', '/v1/news?{}'.format(params))

res = conn.getresponse()
data = res.read()

print(data.decode('utf-8'))

Code Example - jQuery

$.ajax({
    url: 'https://api.mediastack.com/v1/news',
    data: {
      access_key: 'ACCESS_KEY',
      languages: 'fr,-en',
      countries: 'ca,fr',
      limit: 30,
      offset: 30,
    }
  }).done(function(data) {
    console.log(JSON.parse(data));
});

Code Example - Go

package main

import (
	"fmt"
	"io/ioutil"
	"net/http"
	"net/url"
)

func main() {
	baseURL, _ := url.Parse("https://api.mediastack.com")

	baseURL.Path += "v1/news"

	params := url.Values{}
	// Access Key
	params.Add("access_key", "ACCESS_KEY")
	// Parameters
	params.Add("sources", "cnn,bbc")
	params.Add("categories", "sports,general")
	params.Add("languages", "-en") // It will exclude english results

	baseURL.RawQuery = params.Encode()

	req, _ := http.NewRequest("GET", baseURL.String(), nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()

	body, _ := ioutil.ReadAll(res.Body)

	fmt.Println(string(body))
}

Code Example - Ruby

require 'uri'
require 'net/http'

uri = URI('https://api.mediastack.com/v1/news')

params = {
    'access_key' => 'ACCESS_KEY',
    'keywords' => 'Wall street -wolf',
    'categories' => '-entertainment',
    'sort' => 'popularity',
}

uri.query = URI.encode_www_form(params)

response = Net::HTTP.get_response(uri)

puts response.read_body

Business Continuity - API Overages

Ensuring our customers achieve success is paramount to what we do at APILayer. For this reason, we will be rolling out our Business Continuity plan guaranteeing your end users will never see a drop in coverage. Every plan has a certain amount of API calls that you can make in the given month. However, we would never want to cut your traffic or impact user experience negatively for your website or application in case you get more traffic.

What is an overage?

An overage occurs when you go over a quota for your API plan. When you reach your API calls limit, we will charge you a small amount for each new API call so we can make sure there will be no disruption in the service we provide to you and your website or application can continue running smoothly.

Prices for additional API calls will vary based on your plan. See table below for prices per call and example of an overage billing.

Plan Name	Monthly Price	Number of Calls	Overage Price per call	Overage	Total price
Standard	$24.9	10,000	0.0029988	2000	$30.99
Professional	$99.99	50,000	0.00239976	10,000	$123.99
Business	$249.99	250,000	0.001199952	50,000	$309.99

Why does APILayer have overage fees?

Overage fees allow developers to continue using an API once a quota limit is reached and give them time to upgrade their plan based on projected future use while ensuring API providers get paid for higher usage.

How do I know if I will be charged for overages?

When you are close to reaching your API calls limit for the month, you will receive an automatic notification (at 75%, 90% and 100% of your monthly quota). However, it is your responsibility to review and monitor for the plan’s usage limitations. You are required to keep track of your quota usage to prevent overages. You can do this by tracking the number of API calls you make and checking the dashboard for up-to-date usage statistics.

How will I be charged for my API subscription?

You will be charged for your monthly subscription plan, plus any overage fees applied. Your credit card will be billed after the billing period has ended.

What happens if I don’t have any overage fees?

In this case, there will be no change to your monthly invoice. Only billing cycles that incur overages will see any difference in monthly charges. The Business Continuity plan is an insurance plan to be used only if needed and guarantees your end users never see a drop in coverage from you.

What if I consistently have more API calls than my plan allows?

If your site consistently surpasses the set limits each month, you may face additional charges for the excess usage. Nevertheless, as your monthly usage reaches a certain threshold, it becomes more practical to consider upgrading to the next plan. By doing so, you ensure a smoother and more accommodating experience for your growing customer base.

I would like to upgrade my plan. How can I do that?

You can easily upgrade your plan by going to your Dashboard and selecting the new plan that would be more suitable for your business needs. Additionally, you may contact your Account Manager to discuss a custom plan if you expect a continuous increase in usage.

Introducing Platinum Support - Enterprise-grade support for APILayer

Upgrade your APIlayer subscription with our exclusive Platinum Support, an exceptional offering designed to enhance your business’ API management journey. With Platinum Support, you gain access to a host of premium features that take your support experience to a whole new level.

What does Platinum Support include?

	Standard Support	Platinum Support
General review on the issue
Access to knowledge base articles
Email support communication
Regular products updates and fixes
Dedicated account team
Priority Email Support with unlimited communication
Priority bug and review updates
Option for quarterly briefing call with product Management
Features requests as priority roadmap input into product

Priority Email Support: Experience unrivaled responsiveness with our priority email support. Rest assured that your inquiries receive top-priority attention, ensuring swift resolutions to any issues.

Unlimited Communication: Communication is key, and with Platinum Support, you enjoy unlimited access to our support team. No matter how complex your challenges are, our experts are here to assist you every step of the way.

Priority Bug Review and Fixes: Bugs can be a headache, but not with Platinum Support. Benefit from accelerated bug review and fixes, minimizing disruptions and maximizing your API performance.

Dedicated Account Team: We understand the value of personalized attention. That's why Platinum Support grants you a dedicated account team, ready to cater to your specific needs and provide tailored solutions.

Quarterly Briefing Call with Product Team: Stay in the loop with the latest updates and insights from our Product team. Engage in a quarterly briefing call to discuss new features, enhancements, and upcoming developments.

Priority Roadmap Input: Your input matters! As a Platinum Support subscriber, your feature requests receive top priority, shaping our product roadmap to align with your evolving requirements.

Don't settle for the standard when you can experience the exceptional. Upgrade to Platinum Support today and supercharge your APIlayer experience!

Upgrade now