newsdataapi is the official Python SDK for the NewsData.io REST API. It wraps every endpoint (news, market, crypto, sources, count/news, count/market, count/crypto) with consistent retry, pagination, and error handling. It also covers the real-time WebSocket service end to end with NewsDataApiWebSocket: register, list, and delete queries, and stream the matching news as it is published (sync or asyncio).
Installation
pip install newsdataapi
If you use uv:
uv add newsdataapi
Supports Python 3.8 through 3.14. The runtime dependencies are requests (REST) and websockets (real-time streaming). NewsDataApiWebSocket requires Python 3.10 or newer, so websockets is only installed there; on 3.8 and 3.9 the REST client works as usual.
Quickstart
from newsdataapi import NewsDataApiClient
with NewsDataApiClient("YOUR_API_KEY") as client:
response = client.news(q="bitcoin", country="us", language="en")
for article in response["results"]:
print(article["title"], "-", article["url"])
The context-manager form closes the underlying HTTP session cleanly when the block exits. If you prefer not to use with, create the client directly and call client.close() yourself:
from newsdataapi import NewsDataApiClient
client = NewsDataApiClient("YOUR_API_KEY")
try:
response = client.news(q="bitcoin", country="us", language="en")
for article in response["results"]:
print(article["title"], "-", article["url"])
finally:
client.close()
Endpoints
| Method | Endpoint | Notes |
|---|---|---|
news() |
/2/news |
Latest news, or historical news with from_date / to_date |
market() |
/2/market |
Market / financial news |
crypto() |
/2/crypto |
Cryptocurrency news |
sources() |
/2/sources |
Available news sources |
count_news() |
/2/count/news |
News counts per time interval |
count_market() |
/2/count/market |
Market news counts per time interval |
count_crypto() |
/2/count/crypto |
Crypto news counts per time interval |
All parameters are keyword-only. Most accept either a single string or a list[str]; lists are comma-joined for the API. The real-time WebSocket endpoints are covered by NewsDataApiWebSocket (see below).
The count methods return total_results and a results list with one {"date_time": ..., "count": ...} entry per interval (month, day or hour). They page like the news methods, so scroll and paginate work on them too.
See the NewsData.io documentation — or the OpenAPI 3.1 spec — for the full parameter reference.
Upgrading from 0.3.x
The old *_api() methods still work, but they are deprecated and will be removed in a future release. Each one emits a DeprecationWarning naming its replacement:
| Old | New |
|---|---|
latest_api(), archive_api() |
news() |
crypto_api(), market_api(), sources_api() |
crypto(), market(), sources() |
count_api(), crypto_count_api(), market_count_api() |
count_news(), count_crypto(), count_market() |
qInTitle, qInMeta |
q_in_title, q_in_meta |
domainurl, excludedomainurl, excludedomain |
source_url, exclude_source_url, exclude_source_url |
domain |
source_url, with the source's URL (bbc.com) instead of its id (bbc) |
prioritydomain |
source_priority |
excludecountry, excludecategory, excludelanguage |
exclude_country, exclude_category, exclude_language |
excludefield, removeduplicate |
exclude_field, remove_duplicate |
full_content |
content |
totalResults, nextPage in the response |
total_results, next_page |
The article layout changed too: for example url replaces link, and related fields are grouped under media, source and ai. On the count methods from_date and to_date are now optional keyword arguments.
Three ways to consume an endpoint
# 1. Single request (the default).
response = client.news(q="news")
# 2. Auto-merge — follow next_page cursors and return one combined dict.
merged = client.news(q="news", scroll=True, max_result=200)
# 3. Iterate one response per page (a generator).
for page in client.news(q="news", paginate=True, max_pages=5):
process(page["results"])
scroll and paginate are mutually exclusive. scroll=True truncates strictly to max_result; paginate=True stops at max_pages or when the API returns no next_page.
Real-time news (WebSocket)
Requires Python 3.10 or newer. Register a query first — the returned registration_id identifies it from then on:
from newsdataapi import NewsDataApiClient, NewsDataApiWebSocket
client = NewsDataApiClient("YOUR_API_KEY")
ws = NewsDataApiWebSocket(client)
response = ws.websocket_register(q="bitcoin", language="en")
registration_id = response["results"]["registration_id"]
websocket_register takes the same parameter names as the deprecated *_api() methods (q, qInTitle, country, excludecountry, domainurl, full_content, …), not the names news() uses. Registering an identical query twice raises NewsdataAPIError with status_code=409 — the existing id is in e.response_body["results"]["registration_id"]. websocket_fetch() lists every registered query, and websocket_delete(registration_id) removes one.
Then stream. Each yielded response has status, totalResults and results keys, and its articles carry the same fields the deprecated *_api() methods return (article_id, link, pubDate, …), not the news() layout:
for response in ws.stream(registration_id):
for article in response["results"]:
print(article["title"], "-", article["link"])
Use it as a context manager to close the connection promptly when you stop early (otherwise it closes when iteration ends):
with NewsDataApiWebSocket(client) as ws:
for response in ws.stream(registration_id):
print(response["totalResults"])
break
Inside asyncio applications use stream_async() — the same class, same behavior, awaited iteration:
import asyncio
async def main():
async with NewsDataApiWebSocket(client) as ws:
async for response in ws.stream_async(registration_id):
for article in response["results"]:
print(article["title"], "-", article["link"])
asyncio.run(main())
Transient drops (network errors, server restarts, abnormal closes) are reconnected automatically with a capped exponential backoff. Pass reconnect=False to stop on the first disconnect instead. A permanent rejection — bad API key, missing WebSocket entitlement, unknown registration_id, device limit reached, or exhausted quota — raises NewsdataWebSocketAuthError and is not retried:
from newsdataapi import NewsdataWebSocketAuthError, NewsdataWebSocketError
try:
for response in NewsDataApiWebSocket(client).stream(registration_id):
...
except NewsdataWebSocketAuthError as e:
print(f"rejected: {e}")
except NewsdataWebSocketError as e:
print(f"stream error: {e}")
All connection options are keyword-only:
ws = NewsDataApiWebSocket(
client,
base_url="wss://ws.newsdata.io/ws/event", # override for staging / self-hosted / proxied
reconnect=True, # auto-reconnect on transient drops; default True
reconnect_delay=1.0, # seconds before first reconnect (doubles each retry)
reconnect_delay_max=30.0, # cap on the reconnect delay
open_timeout=10.0, # handshake timeout (None disables)
ping_interval=20.0, # keepalive ping interval (None disables)
ping_timeout=20.0, # wait for ping reply before dropping (None disables)
additional_headers={"X-Trace": "abc"}, # extra handshake headers
proxy="http://host:port", # proxy URL
)
Error handling
from newsdataapi import (
NewsdataAPIError,
NewsdataApiKeyLimitExceededError,
NewsdataApiLimitExceededError,
NewsdataAuthError,
NewsdataNetworkError,
NewsdataRateLimitError,
)
try:
client.news(q="news")
except NewsdataAuthError as e:
print(f"bad API key (HTTP {e.status_code})")
except NewsdataApiKeyLimitExceededError:
print("this API key's own credit cap is exhausted")
except NewsdataApiLimitExceededError:
print("account credit pool is exhausted")
except NewsdataRateLimitError as e:
print(f"rate limited; retry after {e.retry_after}s")
except NewsdataAPIError as e:
print(f"API error {e.status_code}: {e.response_body}")
except NewsdataNetworkError as e:
print(f"network failure: {e.original}")
The full hierarchy:
NewsdataException
├── NewsdataValidationError (also a ValueError; carries .param)
├── NewsdataAPIError (carries .status_code, .response_body)
│ ├── NewsdataAuthError (401 / 403)
│ ├── NewsdataRateLimitError (429; carries .retry_after)
│ │ ├── NewsdataApiLimitExceededError (account credit pool exhausted)
│ │ └── NewsdataApiKeyLimitExceededError (this API key's own credit cap exhausted)
│ └── NewsdataServerError (5xx)
├── NewsdataNetworkError (carries .original)
└── NewsdataWebSocketError (real-time stream)
└── NewsdataWebSocketAuthError (handshake 401 / 403, or policy-violation close 1008)
NewsdataApiLimitExceededError and NewsdataApiKeyLimitExceededError are both subclasses of NewsdataRateLimitError, so existing code that only catches NewsdataRateLimitError keeps working unchanged — catch the specific subclasses only if you want to react differently to each. Neither is ever retried.
NewsdataException is always a valid catch-all.
When a request succeeds and include_headers=True, the response dict's response_headers also carries X-API-Limit-Remaining (account pool) and, for API keys with a credit cap, X-APIKEY-Limit-Remaining (that key's own remaining credits).
Save results to CSV
client.save_to_csv(response, folder_path="./out", filename="latest_news")
# Or set folder_path once on the client and reuse:
client = NewsDataApiClient(apikey, folder_path="./out")
client.save_to_csv(response, filename="latest_news")
save_to_csv returns a pathlib.Path. Nested fields get one column each, named with dots (source.name, ai.sentiment.label); lists are comma-joined, and lists of objects are written as JSON. Responses from the deprecated *_api() methods keep the old format: dict and list cells are stringified (key:value,key:value for dicts, comma-joined for lists). Quoting is delegated to the standard csv.DictWriter, so the output round-trips correctly through any CSV reader.
The function is also importable as a standalone:
from newsdataapi import save_to_csv
save_to_csv(response, folder_path="./out", filename="latest_news")
Configuration
client = NewsDataApiClient(
apikey="...",
request_timeout=30, # seconds; default 30
max_retries=5, # default 5
retry_backoff=2.0, # base seconds, exponential; default 2.0
retry_backoff_max=60.0, # cap on a single retry sleep; default 60.0
pagination_delay=1.0, # seconds between pages; default 1.0
max_result=None, # cap on merged results in scroll mode; default None (no cap)
max_pages=None, # cap on pages yielded in paginate mode; default None (no cap)
proxies={"https": "..."}, # passed with every request
accept_language="en", # Accept-Language header
include_headers=False, # if True, returned dicts include response_headers
base_url="...", # API root; override for staging / proxied environments
session=my_session, # inject your own requests.Session
folder_path="./out", # default folder for save_to_csv; default None
)
base_url (and set_base_url()) is the API root without a version segment; the default is https://newsdata.io/api, and the client adds /1/... or /2/... itself. Before 0.4.0 it included the version (https://newsdata.io/api/1/), so drop the trailing /1/ if you override it.
A request that fails with a server error, a rate limit, or a network error is attempted 5 times by default, sleeping 2 s, 4 s, 8 s and 16 s between attempts (30 s in total; a single sleep never exceeds retry_backoff_max). A 429 response is instead retried after the server's Retry-After plus one second (both integer-seconds and HTTP-date forms are parsed); when Retry-After is longer than retry_backoff_max, the client does not wait and raises NewsdataRateLimitError with retry_after set. The API key is redacted in log output.
Development
This project uses uv for environment and lock management.
git clone https://github.com/newsdataapi/python-client
cd python-client
uv sync # creates .venv, installs runtime + dev deps from uv.lock
Run the suite:
uv run pytest # unit tests only (default)
PYTEST_TOKEN=<api-key> uv run pytest -m integration # live-API tests
PYTEST_TOKEN=<api-key> uv run pytest -m "" # all tests
uv run ruff check src/ tests/ examples/
uv run mypy src/
Dev dependencies live in PEP 735 [dependency-groups].dev (uv-native). Plain pip install -e ".[dev]" will not pick them up; if you can't use uv, install the contents of the dev group in pyproject.toml by hand.
Related libraries
Official Newsdata.io clients across languages and runtimes:
- Node.js — newsdataapi/newsdata-nodejs-client (npm)
- React (hooks) — newsdataapi/newsdata-reactjs-client (npm)
- PHP — newsdataapi/php-client (Packagist)
- Java — newsdataapi/newsdata-java-sdk (Maven Central)
- .NET — newsdataapi/newsdata-dotnet-sdk (NuGet)
- Go — newsdataapi/newsdata-go-client (pkg.go.dev)
- Dart / Flutter — newsdataapi/newsdata-flutter-client (pub.dev)
- MCP Server (AI assistants) — newsdataapi/newsdata.io-mcp (PyPI)
Also see free news datasets for ML / NLP work.
License
MIT. See the LICENSE file.
Metadata
Release files for newsdataapi 0.4.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| newsdataapi-0.4.0.tar.gz | 139.5 kB | With provenance | Details for newsdataapi-0.4.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| newsdataapi-0.4.0-py3-none-any.whl | Python 3 | none | any | Details for newsdataapi-0.4.0-py3-none-any.whl |
Total release size: 168.4 kB
Release files / newsdataapi-0.4.0.tar.gz
| Download URL | newsdataapi-0.4.0.tar.gz |
|---|---|
| Size | 139.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
69d39c0e08a0bbf1ad95e9691f20e3a2a51617bf2bdf855c8c5d5b7cf6a83910
|
|
BLAKE2b-256 checksum How to use checksums |
4269d922252ec28aa016b4ae77e72a75ea71948499501d9057695f3f23058baf
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.
Transparency logRelease files / newsdataapi-0.4.0-py3-none-any.whl
| Download URL | newsdataapi-0.4.0-py3-none-any.whl |
|---|---|
| Size | 28.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
303a618f208fd7a66276a378cc8cbcf299a26b75507faf4a69e6fcf1e6e73c50
|
|
BLAKE2b-256 checksum How to use checksums |
fce1717c78a83d99a863d127ceab4edadc42f03eedcf672e25cebc36c8ff297e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.
Transparency logSecurity for newsdataapi 0.4.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for newsdataapi-0.4.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.