Get started

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

Secondly 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.

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 top headlines from a news source

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 top and breaking news headlines across over a hundred top publications and blogs in near real time.

Let's make a request to get the top headlines from BBC News. We'll use the /top-headlines endpoint for this.

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);

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

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 5,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 lesser articles that don't make it as a top story.

curl https://newsapi.org/v2/everything -G \
    -d q=Apple \
    -d from=2017-12-12 \
    -d sortBy=popularity \
    -d apiKey={API_KEY}
var url = 'https://newsapi.org/v2/everything?' +
          'q=Apple&' +
          'from=2017-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=2017-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=2017-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=2017-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.