News API v2 migration guide

This guide will explain the differences between v1 and v2 of News API, and demonstrate how to migrate from v1 to v2 in the easiest way.

v1 will remain operational for the foreseeable future, so if v1 fulfils your requirements then there's no urgent need to migrate.

New endpoint

The main change in v2 has been the addition of a new endpoint (/v2/everything). This new endpoint can be used to search every recent article a source has published, on up to 80,000 sources.

However, if all you're interested in is live top headlines then you can completely ignore this new endpoint.

You now have the option to search for headlines by keyword. You can mix this in with any of the other existing params to focus the search or leave it wide open. Just send the q param in your request querystring.

Like this:

URL change for getting top headlines

The /v1/articles endpoint has been renamed to /v2/top-headlines to better describe what kind of articles it returns, so /v2/top-headlines is the endpoint you need to switch to if you want to continue using News API for the same function as v1. We've increased the number of news sources supported, focusing especially on expanding the range of countries and languages available. New sources will be added frequently.

There's no urgent need to move over to v2 as we'll be keeping v1 around for now, but we won't be adding any more sources to v1. v2 on the other hand will be updated with new sources frequently.

Retrieve multiple sources in a single query

Along with the URL change, you are now able to retrieve headlines from multiple sources in a single request, and this is now the default way to lookup headlines. This means that the structure of the response has also changed slightly to allow for a response containing multiple sources.

Here's a before and after of a similar request for top headlines from Associated Press. In this request we're only asking for one source for comparison's sake, but you can append other sources to the sources param in v2, separated by commas. Notice the changes in bold, and the differing response structure to support multiple sources in a single response.

From this:

To this:

Sources endpoint now requires your API key

The /sources endpoint now requires API key authentication. Its usage is now measured against your monthly API quota, so please try and cache it on your side where possible and only check for updates daily or weekly.