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:
- Obtain your v3 API token.
- Review the
API changes v2 vs v3.
- Have Python with the
requests
library installed.
Basic setup
To get started, change authentication and base URLs:
import requests
from typing import Dict, Optional
API_KEY: str = "YOUR_API_KEY"
BASE_URL: str = "https://api.newscatcherapi.com/v2"
HEADERS: Dict[str, str] = {"x-api-key": API_KEY}
def search_news(query: str) -> Optional[Dict]:
try:
response = requests.get(
f"{BASE_URL}/search",
headers=HEADERS,
params={"q": query}
)
response.raise_for_status()
return response.json()
except requests.exceptions.RequestException as e:
print(f"Error making request: {e}")
return None
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
Rename date parameters
Replace from
and to
with from_
and to_
respectively:
params = {
"q": "Tesla",
"from": "2024/01/01",
"to": "2024/01/31"
}
Update topic to theme
Replace topic
with theme
and enable NLP:
params = {
"q": "Tesla",
"topic": "tech"
}
Update search fields
Replace search_in
format:
params = {
"q": "Tesla",
"search_in": "title_summary"
}
Complete search example
import requests
from typing import Dict, Optional
API_KEY: str = "YOUR_API_KEY"
BASE_URL: str = "https://api.newscatcherapi.com/v2"
HEADERS: Dict[str, str] = {"x-api-key": API_KEY}
def search_articles(
query: str,
from_date: str,
to_date: str,
topic: str
) -> Optional[Dict]:
try:
response = requests.get(
f"{BASE_URL}/search",
headers=HEADERS,
params={
"q": query,
"from": from_date,
"to": to_date,
"topic": topic,
"search_in": "title_summary",
"lang": "en"
}
)
response.raise_for_status()
data = response.json()
articles = []
for article in data.get("articles", []):
articles.append({
"title": article.get("title"),
"url": article.get("link"),
"source": article.get("clean_url"),
"published_date": article.get("published_date"),
"content": article.get("summary")
})
return {
"total_articles": data.get("total_hits", 0),
"articles": articles
}
except requests.exceptions.RequestException as e:
print(f"Error making request: {e}")
return None
Usage example
# Search for Tesla news in tech
result = search_articles(
query="Tesla",
from_date="2024/01/01",
to_date="2024/01/31",
topic="tech"
)
Response structure changes
{
"status": "ok",
"total_hits": 521,
"page": 1,
"total_pages": 6,
"page_size": 100,
"articles": [
{
"title": "Tesla lowers range estimates for Model X, S, Y cars",
"author": "Matt Binder",
"published_date": "2024-01-05 18:11:03",
"link": "https://mashable.com/article/tesla-range-estimates",
"clean_url": "mashable.com", // Domain name, renamed to domain_url in v3
"excerpt": "The change follows...", // Brief summary, renamed to description in v3
"summary": "Tesla has updated...", // Full text, renamed to content in v3
"topic": "tech", // Topic classification, moved to nlp.theme in v3
"country": "US",
"language": "en",
"authors": "Matt Binder",
"is_opinion": false,
"twitter_account": "@mashable",
"_score": 11.959808, // Renamed to score in v3
"_id": "e623cee7239059b40ca40234" // Renamed to id in v3
}
],
"user_input": {
"q": "Tesla",
"search_in": ["title_summary_en"],
"lang": ["en"],
"from": "2024-01-01 00:00:00",
"to": "2024-01-31 00:00:00",
"ranked_only": "True",
"sort_by": "relevancy",
"page": 1,
"size": 100,
"not_sources": [],
"topic": "tech" // Renamed to theme in v3
}
}
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
Update topic to theme
Replace topic
with theme
and enable NLP:
params = {
"topic": "business",
"countries": "US,GB"
}
Time range specification
Optionally specify time range with the when
parameter:
params = {
"countries": "US,GB",
"when": "24h" # Optional, defaults to "7d"
}
Complete latest headlines example
import requests
from typing import Dict, Optional
API_KEY: str = "YOUR_API_KEY"
BASE_URL: str = "https://api.newscatcherapi.com/v2"
HEADERS: Dict[str, str] = {"x-api-key": API_KEY}
def get_latest_headlines(
countries: str,
topic: str
) -> Optional[Dict]:
try:
response = requests.get(
f"{BASE_URL}/latest_headlines",
headers=HEADERS,
params={
"countries": countries,
"topic": topic,
"lang": "en"
}
)
response.raise_for_status()
data = response.json()
articles = []
for article in data.get("articles", []):
articles.append({
"title": article.get("title"),
"url": article.get("link"),
"source": article.get("clean_url"),
"published_date": article.get("published_date"),
"content": article.get("summary")
})
return {
"total_articles": data.get("total_hits", 0),
"articles": articles
}
except requests.exceptions.RequestException as e:
print(f"Error making request: {e}")
return None
Usage example
# Get latest business headlines from US and GB
result = get_latest_headlines(
countries="US,GB",
topic="business"
)
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
{
"status": "ok",
"total_hits": 10000,
"page": 1,
"total_pages": 200,
"page_size": 50,
"articles": [
{
"title": "Donald Trump Nominates Fox Business Host Sean Duffy",
"author": "Ted Johnson",
"published_date": "2024-11-18 23:07:23",
"published_date_precision": "full",
"link": "https://deadline.com/2024/11/trump-sean-duffy-1236180738",
"clean_url": "deadline.com", // Domain name, renamed to domain_url in v3
"excerpt": "Donald Trump has gone...", // Brief text, renamed to description in v3
"summary": "Sean Duffy in 2018...", // Full text, renamed to content in v3
"topic": "business", // Moved to nlp.theme in v3
"country": "US",
"language": "en",
"authors": "Where Img,Class,Display Inline,Ted Johnson",
"media": "https://deadline.com/wp-content/uploads/2024/11/img.jpg",
"is_opinion": false,
"twitter_account": "@tedstew",
"_score": null, // Renamed to score in v3
"_id": "75382d1ff5336599bce837ab168bb34b" // Renamed to id in v3
}
],
"user_input": {
"lang": ["en"],
"countries": ["US", "GB"],
"topic": "business", // Renamed to theme in v3
"from": "2024-11-11 23:14:24"
}
}
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
Remove topic parameter
The topic
parameter is removed in v3. Instead, use new filtering options:
params = {
"lang": "en",
"countries": "US",
"topic": "news"
}
Enable additional metadata
Use include_additional_info
to get enhanced source information:
params = {
"lang": "en",
"countries": "US"
}
Complete sources example
import requests
from typing import Dict, Optional
API_KEY: str = "YOUR_API_KEY"
BASE_URL: str = "https://api.newscatcherapi.com/v2"
HEADERS: Dict[str, str] = {"x-api-key": API_KEY}
def get_sources(
countries: str,
lang: str = "en"
) -> Optional[Dict]:
try:
response = requests.get(
f"{BASE_URL}/sources",
headers=HEADERS,
params={
"countries": countries,
"lang": lang
}
)
response.raise_for_status()
data = response.json()
return {
"message": data.get("message"),
"sources": data.get("sources", []) # List of domain strings
}
except requests.exceptions.RequestException as e:
print(f"Error making request: {e}")
return None
Usage example
# Get US news sources
result = get_sources(countries="US")
# Access source domains (returns list of strings)
sources = result["sources"] # e.g., ["example.com", "news.com"]
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
{
"message": "Maximum sources displayed according to your plan is set to 1000",
"sources": [
// Simple array of domain strings
"wn.com",
"yahoo.com",
"headtopics.com"
// ...
],
"user_input": {
"lang": ["en"],
"countries": ["US"],
"topic": "news" // Replaced by more specific classification in v3
}
}
Next steps
- Test your migrated implementation.
- Review How-to documentation for v3 usage.
- Explore
News API v3 endpoints
for additional capabilities.