Get started

To get started you'll need an API key. They're free for development, open-source, and non-commercial use and you can get one over here.

Also we're assuming you know how to make web requests in your chosen programming language. We've included some crude ways to do this in our examples below if you need a place to start. Alternatively you can use one of our client libraries.

Now let's consider two of the most popular use cases for News API and walk through each one:


I want to show my users live top and breaking news headlines

News API is great as a data source for news tickers and other applications where you want to show your users live headlines. We track headlines in 7 categories across over 50 countries, and at over a hundred top publications and blogs, in near real time.

Let's make a request to get live top headlines in the US right now. We'll use the /top-headlines endpoint for this.

curl https://newsapi.org/v2/top-headlines -G \
    -d country=us \
    -d apiKey=API_KEY
var url = 'https://newsapi.org/v2/top-headlines?' +
          'country=us&' +
          'apiKey=API_KEY';
var req = new Request(url);
fetch(req)
    .then(function(response) {
        console.log(response.json());
    })
require 'open-uri'
url = 'https://newsapi.org/v2/top-headlines?'\
      'country=us&'\
      'apiKey=API_KEY'
req = open(url)
response_body = req.read
puts response_body
import requests
url = ('https://newsapi.org/v2/top-headlines?'
       'country=us&'
       'apiKey=API_KEY')
response = requests.get(url)
print response.json()
using System.Net;
                            
var url = "https://newsapi.org/v2/top-headlines?" +
          "country=us&" +
          "apiKey=API_KEY";
                            
var json = new WebClient().DownloadString(url);
                            
Console.WriteLine(json);

This returns a JSON object with the results in an array we can iterate over.

If you want headlines just from a specific source, for example BBC News, we can do that too.

curl https://newsapi.org/v2/top-headlines -G \
    -d sources=bbc-news \
    -d apiKey=API_KEY
var url = 'https://newsapi.org/v2/top-headlines?' +
          'sources=bbc-news&' +
          'apiKey=API_KEY';
var req = new Request(url);
fetch(req)
    .then(function(response) {
        console.log(response.json());
    })
require 'open-uri'
url = 'https://newsapi.org/v2/top-headlines?'\
      'sources=bbc-news&'\
      'apiKey=API_KEY'
req = open(url)
response_body = req.read
puts response_body
import requests
url = ('https://newsapi.org/v2/top-headlines?'
       'sources=bbc-news&'
       'apiKey=API_KEY')
response = requests.get(url)
print response.json()
using System.Net;
                            
var url = "https://newsapi.org/v2/top-headlines?" +
          "sources=bbc-news&" +
          "apiKey=API_KEY";
                            
var json = new WebClient().DownloadString(url);
                            
Console.WriteLine(json);

If you're wondering how we knew that the identifier for BBC News was bbc-news, there's a news source list you can refer to, or you can use the sources endpoint.


As well as tracking top headlines, we also index every article published by over 30,000 news sources and blogs. Think of us as Google for news articles that you can search programmatically!

In this example we want to find all articles published today that mention Apple and sort them by most popular source first (i.e. Engadget articles will be returned ahead of Mom and Pop's Little iPhone Blog).

We want to broaden the scope to more than just the top headlines here, so we'll use the /everything endpoint. The /everything endpoint includes all the articles from /top-headlines, plus all the millions of articles that don't make it as a top story, or that aren't breaking news anymore.

curl https://newsapi.org/v2/everything -G \
    -d q=Apple \
    -d from=2018-12-12 \
    -d sortBy=popularity \
    -d apiKey=API_KEY
var url = 'https://newsapi.org/v2/everything?' +
          'q=Apple&' +
          'from=2018-12-12&' +
          'sortBy=popularity&' +
          'apiKey=API_KEY';

var req = new Request(url);

fetch(req)
    .then(function(response) {
        console.log(response.json());
    })
require 'open-uri'

url = 'https://newsapi.org/v2/everything?'\
      'q=Apple&'\
      'from=2018-12-12&'\
      'sortBy=popularity&'\
      'apiKey=API_KEY'

req = open(url)

response_body = req.read

puts response_body
import requests

url = ('https://newsapi.org/v2/everything?'
       'q=Apple&'
       'from=2018-12-12&'
       'sortBy=popularity&'
       'apiKey=API_KEY')

response = requests.get(url)

print r.json
using System.Net;
                            
var url = "https://newsapi.org/v2/everything?" +
          "q=Apple&" +
          "from=2018-12-12&" +
          "sortBy=popularity&" +
          "apiKey=API_KEY";
                            
var json = new WebClient().DownloadString(url);
                            
Console.WriteLine(json);

And bingo:


For more details about the endpoints and modifiers you can lookup articles with, including possible responses, check the full documentation.