GNews API Python Client

Official Python client for the GNews API: search news articles and top headlines from 80,000+ sources in 41 languages.

• No dependencies, Python 3.10+
• Typed responses (Article, Source) with editor autocompletion
• One exception per API error (invalid key, quota reached, rate limit...)
• Automatic retry on rate limit (429), server (5xx) and network errors
• Lazy pagination helpers that stop at a requested limit

Installation

pip install gnews-io-python

Note: gnews on PyPI is an unrelated Google News scraper and gnewsio is an unofficial client. The official client is gnews-io-python, imported as gnews_io.

Quick start

Get a free API key at gnews.io/register.

from gnews_io import GNews

client = GNews("YOUR_API_KEY")  # or set the GNEWS_API_KEY environment variable and call GNews()

result = client.search("bitcoin", lang="en", max=10)

print(result.total_articles)
for article in result.articles:
    print(article.published_at, article.source.name, article.title)

Search

from datetime import datetime, timezone

result = client.search(
    '"Federal Reserve" AND rates',
    lang="en",
    country="us",
    max=10,
    in_=["title", "description"],
    from_=datetime(2026, 10, 1, tzinfo=timezone.utc),
    sortby="relevance",
)

The query supports quotes, AND, OR, NOT and parentheses: see the query syntax.

Top headlines

result = client.top_headlines("business", lang="en", country="us", max=10)

Categories: general (default), world, nation, business, technology, entertainment, sports, science, health.

Parameters

in_ and from_ end with an underscore because in and from are Python keywords.

Full reference: docs.gnews.io.

Response

search and top_headlines return an ArticlesResponse:

Each Article has id, title, description, content, url, image, published_at (timezone-aware datetime, UTC), lang and source (id, name, url, country). source.country is only returned by search.

On the Free plan, content is truncated. Full content is available on paid plans.

Pagination

iter_search and iter_top_headlines take the same parameters as search and top_headlines, fetch the next page only when you reach it, and stop at limit, at the last page or at the API's 1,000-article cap:

for article in client.iter_search("climate", lang="en", max=10, limit=50):
    print(article.title)

Each page is one API request. You can also pass page yourself to search and top_headlines.

Error handling

All errors inherit from GNewsError, which exposes status (HTTP code) and errors (the API error payload).

from gnews_io import GNews, GNewsError, QuotaExceededError

try:
    result = client.search("bitcoin")
except QuotaExceededError:
    print("Daily quota reached, it resets at 00:00 UTC")
except GNewsError as e:
    print(e.status, e)

Rate limit, server and network errors are retried twice with a short randomized backoff (about 1 s, then 2 s) before raising. Change it with GNews(max_retries=0).

Options

client = GNews(
    "YOUR_API_KEY",
    timeout=10.0,     # seconds per request
    max_retries=2,    # retries on 429, 5xx and network errors
)

Development

pip install -e ".[dev]"
python -m unittest discover -v
mypy

License

MIT