Python NewsAPI.org → newsdata.io Migration Kit

Migrating an existing Python app off the NewsAPI.org client (newsapi-python) and onto newsdata.io? This repo gives you a drop-in compatibility layer plus a step-by-step migration guide so you can switch with minimal code changes.

The newsdata_compat.NewsDataClient class exposes the same method names and return shape as newsapi.NewsApiClient — get_top_headlines(), get_everything() and get_sources() — but talks to the newsdata.io REST API (https://newsdata.io/api/1) under the hood and translates the responses back into the NewsAPI.org format your code already expects.

Everything here is built and tested against the newsdata.io FREE tier.

Why migrate?

	NewsAPI.org	newsdata.io
Auth	X-Api-Key header / apiKey param	apikey query param
Latest news	/v2/top-headlines	/api/1/news
Search	/v2/everything	/api/1/news?q=
Sources	/v2/sources	/api/1/sources
Pagination	numeric page	opaque nextPage token
Free tier	limited, dev only	generous, production-friendly

Quick start

git clone https://github.com/your-account/python-newsapi-to-newsdata-migration.git
cd python-newsapi-to-newsdata-migration
pip install -r requirements.txt
export NEWSDATA_API_KEY="your_free_api_key_here"   # Windows: set NEWSDATA_API_KEY=...
python -m examples.demo

Get a free key at https://newsdata.io/register.

The drop-in change

Before (NewsAPI.org):

from newsapi import NewsApiClient

client = NewsApiClient(api_key="YOUR_NEWSAPI_KEY")
resp = client.get_top_headlines(q="bitcoin", language="en", country="us")
for article in resp["articles"]:
    print(article["title"], "-", article["source"]["name"])

After (newsdata.io — change two lines):

from newsdata_compat import NewsDataClient

client = NewsDataClient()  # reads NEWSDATA_API_KEY from the environment
resp = client.get_top_headlines(q="bitcoin", language="en", country="us")
for article in resp["articles"]:
    print(article["title"], "-", article["source"]["name"])

The loop body is unchanged: the compat layer returns the same {"status", "totalResults", "articles": [...]} structure, where each article has title, description, url, urlToImage, publishedAt, content, author and a nested source dict.

API reference (compat layer)

NewsDataClient(api_key=None, session=None)

If api_key is omitted it is read from NEWSDATA_API_KEY. Raises ValueError if neither is provided.

get_top_headlines(q=None, sources=None, category=None, language=None, country=None, page=None)

Maps to GET /news. Returns NewsAPI-shaped dict.

get_everything(q=None, sources=None, domains=None, language=None, sort_by=None, page=None)

Maps to GET /news (newsdata.io uses one news endpoint for both). domains maps to newsdata.io's domain filter.

get_sources(category=None, language=None, country=None)

Maps to GET /sources.

Pagination differences (important)

NewsAPI.org uses an incrementing integer page. newsdata.io uses an opaque nextPage token returned in each response. The compat layer surfaces this token in two places so you can choose your migration style:

• The returned dict includes a nextPage key (the raw newsdata.io token).
• You may pass that token straight back as the page= argument to fetch the next page.

resp = client.get_everything(q="climate")
while resp.get("nextPage"):
    resp = client.get_everything(q="climate", page=resp["nextPage"])

Error handling

All API errors raise newsdata_compat.NewsDataException (aliased as NewsAPIException for familiarity). The client handles, with clear messages:

• 401 — invalid/missing API key
• 429 — rate limit reached (back off and retry)
• 403 / 422 — a requested feature requires a paid plan (see below)
• empty results — returns an empty articles list instead of crashing

Features that require a PAID newsdata.io plan

The following are not available on the free tier. This kit never relies on them in the core flow; they are exposed only as opt-in flags that degrade gracefully (the client detects the 403/422 "upgrade your plan" response, logs a warning, and returns results without the paid feature):

• sentiment / sentiment analysis
• AI fields: ai_tag, ai_region, ai_org, ai_summary
• the historical /archive endpoint and long date ranges
• advanced full-text query operators

Configuration

Env var	Required	Description
NEWSDATA_API_KEY	yes	Your newsdata.io API key (free tier works).

Project layout

newsdata_compat/
  __init__.py      # public exports
  client.py        # NewsDataClient drop-in + response translation
  errors.py        # NewsDataException / NewsAPIException alias
examples/
  demo.py          # runnable before/after demo

License

MIT — see headers. Not affiliated with NewsAPI.org. Built to showcase newsdata.io.