This guide provides practical instructions for migrating from News API v2 to v3, with Python code examples for each endpoint.

​
Prerequisites

Before starting your migration:

  1. Obtain your v3 API token.
  2. Review the API changes v2 vs v3.
  3. Have Python with the requests library installed.

​
Basic setup

To get started, change authentication and base URLs:

​
Search endpoint migration

The search endpoint enables news search with enhanced filtering capabilities in v3. Key changes include parameter renaming, updated response fields, and new filtering options.

​
Parameter changes

1

Rename date parameters

Replace from and to with from_ and to_ respectively:

2

Update topic to theme

Replace topic with theme and enable NLP:

3

Update search fields

Replace search_in format:

​
Complete search example

​
Usage example

​
Response structure changes

​
Latest headlines migration

The latest headlines endpoint provides access to recent news articles. Migration involves similar parameter updates as the search endpoint, with additional time-based filtering options.

​
Parameter changes

1

Update topic to theme

Replace topic with theme and enable NLP:

2

Time range specification

Optionally specify time range with the when parameter:

​
Complete latest headlines example

​
Usage example

​
Additional filtering options

V3 provides enhanced filtering capabilities for latest headlines:

params = {
    "theme": "Business",
    "countries": "US,GB",
    "include_nlp_data": True
    "is_headline": True,          # Filter for homepage articles
    "is_paid_content": False,     # Exclude paywalled content
    "word_count_min": 200,        # Minimum article length
    "word_count_max": 1000        # Maximum article length
}

For a complete list of /latest_headlines parameters, see the Latest headlines reference documentation.

​
Response structure changes

​
Sources endpoint migration

The sources endpoint in v3 provides enhanced metadata about news sources. Key changes include the removal of the topic parameter and introduction of new filtering capabilities.

​
Parameter changes

1

Remove topic parameter

The topic parameter is removed in v3. Instead, use new filtering options:

2

Enable additional metadata

Use include_additional_info to get enhanced source information:

​
Complete sources example

​
Usage example

​
Advanced filtering options

V3 provides additional parameters for precise source filtering:

params = {
    "lang": "en",
    "countries": "US",
    "include_additional_info": True,
    "source_name": "tech,news",        # Search within source names
    "is_news_domain": True,            # Filter for news domains only
    "news_domain_type": "Original Content",  # Can be "Original Content" or "Aggregator"
    "from_rank": 1,                    # Filter by rank range
    "to_rank": 1000
}

​
Response structure changes

​
Next steps

  1. Test your migrated implementation.
  2. Review How-to documentation for v3 usage.
  3. Explore News API v3 endpoints for additional capabilities.

Was this page helpful?

API changes v2 vs v3Use boolean operators