Google News API Python Client

Unofficial Python client for Google News RSS. Search trusted publishers, run batch research, fetch top stories, decode article URLs, and use the same tools from async code, the command line, or an MCP server.

This package is not an official Google API. It uses Google News RSS feeds by default and offers optional SearchAPI-backed modes when you need provider URLs or richer snippets.

Install

pip install google-news-api

Verify the installed command and package version:

google-news --version

Quickstart

from google_news_api import GoogleNewsClient

with GoogleNewsClient(language="en", country="US") as client:
    articles = client.search("artificial intelligence", when="24h", max_results=5)

for article in articles:
    print(article["title"])
    print(article["source"])
    print(article["published"])
    print(article["link"])

Command Line

The package also installs a google-news command for quick searches and exports:

google-news search "artificial intelligence" --when 24h --max-results 5

Limit results to trusted publishers and exclude unwanted domains:

google-news search "artificial intelligence" \
  --include-domain reuters.com \
  --include-domain apnews.com \
  --exclude-domain youtube.com \
  --when 7d

Run several research queries with the same filters:

google-news batch "AI regulation" "semiconductor supply chain" \
  --include-domain reuters.com \
  --format json

Fetch local Google News headlines:

google-news location "Chicago" --max-results 10 --format json

Build safe advanced queries:

google-news search "python" \
  --exact-phrase "programming language" \
  --any-word "rust" \
  --any-word "go" \
  --exclude-word "java" \
  --in-title "tutorial" \
  --show-query

Monitor a topic for new coverage:

# Run in a terminal to poll every 5 minutes and append new articles
google-news watch "semiconductor supply chain" \
  --when 24h \
  --interval 300 \
  --state .news-state.json \
  --format jsonl \
  --output new-articles.jsonl

# Run once in a cron job, emitting only unseen articles since the last run
google-news watch "semiconductor supply chain" \
  --when 24h \
  --once \
  --state .news-state.json \
  --format jsonl \
  --output new-articles.jsonl \
  --force

Export machine-readable results as JSON or CSV:

google-news search "python" --format json
google-news top --topic TECHNOLOGY --max-results 10 --format csv

Write any command directly to a UTF-8 file:

google-news search "python" --format json --output python-news.json
google-news batch "AI regulation" "semiconductors" \
  --format csv \
  --output research.csv

Existing files are protected by default. Pass --force to replace one, or use --output - to write explicitly to standard output.

Decode Google News RSS links to publisher URLs when exporting:

google-news search "climate change" --when 7d --decode-links --format json

Extract article text with the optional extraction dependencies:

pip install "google-news-api[extract]"
google-news search "climate change" --when 7d --extract-text --format json

Use the same SearchAPI modes as the Python client:

google-news search "artificial intelligence regulation" \
  --mode searchapi_light \
  --format json

What You Get

Article Results

Default Google News RSS results use this shape:

{
    "title": "Article title",
    "link": "https://news.google.com/rss/articles/...",
    "published": "Tue, 16 Jun 2026 12:00:00 GMT",
    "summary": "Article summary",
    "source": "Publisher name",
    "id": "Google News article ID",
}

Notes:

• In default mode, link is the Google News RSS article URL.
• In SearchAPI modes, link is usually the provider or publisher URL returned by SearchAPI.
• id is always present in normalized results. It is a Google News article ID when available, and None when the provider does not return one.

Common Usage

Top News

from google_news_api import GoogleNewsClient

with GoogleNewsClient(country="US", language="en") as client:
    articles = client.top_news(topic="TECHNOLOGY", max_results=10)

Search With Time Filters

with GoogleNewsClient() as client:
    recent = client.search("climate change", when="24h", max_results=10)
    dated = client.search(
        "Ukraine war",
        after="2024-01-01",
        before="2024-03-01",
        max_results=10,
    )

Use when for relative time filters such as "1h", "24h", or "7d". Use after and before for YYYY-MM-DD date range searches. when cannot be combined with after or before.

Search Trusted Domains

with GoogleNewsClient() as client:
    articles = client.search(
        "artificial intelligence",
        include_domains=["reuters.com", "apnews.com"],
        exclude_domains=["youtube.com"],
        when="7d",
    )

Domain filters are optional and work with search() and batch_search() on both synchronous and asynchronous clients. Existing query strings and result dictionaries are unchanged.

Decode Google News URLs

with GoogleNewsClient() as client:
    article = client.search("python", max_results=1)[0]
    publisher_url = client.decode_url(article["link"])

Extract Full Article Text

Install the optional extraction dependencies on Python 3.10 or newer:

pip install "google-news-api[extract]"

ArticleEnricher preserves input order and dictionaries. It decodes Google News links, keeps the original URL in google_link, and adds text when the publisher page is reachable:

from google_news_api import ArticleEnricher, GoogleNewsClient

with GoogleNewsClient() as client:
    articles = client.search("climate policy", when="24h", max_results=5)
    enriched = ArticleEnricher(client).enrich(articles, extract_text=True)

for article in enriched:
    print(article.get("text", ""))

Async code uses the matching enricher:

import asyncio

from google_news_api import AsyncArticleEnricher, AsyncGoogleNewsClient


async def main():
    async with AsyncGoogleNewsClient() as client:
        articles = await client.search("climate policy", max_results=5)
        return await AsyncArticleEnricher(client).enrich(
            articles,
            extract_text=True,
        )


enriched = asyncio.run(main())

Extraction does not bypass paywalls, authentication, robots controls, or publisher blocking. A failed page affects only that article. SearchAPI results that already contain publisher URLs can be extracted without URL decoding.

Async Client

import asyncio

from google_news_api import AsyncGoogleNewsClient


async def main():
    async with AsyncGoogleNewsClient() as client:
        articles = await client.search("machine learning", when="7d", max_results=5)
        urls = await client.decode_urls([article["link"] for article in articles])
        return urls


asyncio.run(main())

Search Modes

The search(), batch_search(), and top_news() methods support these modes:

SearchAPI modes require an API key:

export SEARCHAPI_API_KEY="your-api-key"

PowerShell:

$env:SEARCHAPI_API_KEY = "your-api-key"

with GoogleNewsClient(language="en", country="US") as client:
    articles = client.search(
        "artificial intelligence regulation",
        max_results=10,
        mode="searchapi_light",
    )

Use "default" first unless you specifically need SearchAPI data.

MCP Server

Install optional MCP dependencies on Python 3.10 or newer:

pip install "google-news-api[mcp]"

Run the packaged stdio server:

google-news-mcp

The packaged entrypoints are the google-news-mcp command and the google_news_api.mcp_server module. The source-tree mcp_server/googlenews.py script remains as a local development compatibility wrapper.

The MCP server exposes news_search, batch_news_search, top_news, and location_news. By default, the tools decode Google News links to publisher URLs, store the original URL in google_link, and extract article text through the same AsyncArticleEnricher used by Python callers. The tools also accept mode for the same search modes as the Python client.

For faster headline-only calls:

result = await client.news_search(
    query="artificial intelligence",
    when="24h",
    max_results=10,
    decode_links=False,
    extract_text=False,
)

MCP tools accept the same search modes as the Python client. See mcp_server/README.md for tool parameters and response format.

Configuration

Available topics:

• "WORLD"
• "NATION"
• "BUSINESS"
• "TECHNOLOGY"
• "ENTERTAINMENT"
• "SPORTS"
• "SCIENCE"
• "HEALTH"

Errors

from google_news_api.exceptions import (
    ConfigurationError,
    HTTPError,
    ParsingError,
    RateLimitError,
    ValidationError,
)

The client raises specific exceptions for invalid configuration, invalid query parameters, HTTP failures, rate limits, and feed parsing failures.

Development

git clone https://github.com/ma2za/google-news-api.git
cd google-news-api
poetry install --with dev --all-extras
poetry run pre-commit install

Run the same checks as the GitHub Actions workflow before opening a pull request:

poetry run black --check google_news_api tests examples mcp_server
poetry run isort --check-only google_news_api tests examples mcp_server
poetry run flake8 google_news_api tests examples mcp_server
poetry run pytest -m "not integration" --strict-markers

The default test command skips tests that make live network calls. To include live Google News integration tests:

poetry run pytest -m integration --run-integration --strict-markers

Contributing

See CONTRIBUTING.md for setup, offline and live validation, and pull request requirements.

Public compatibility commitments are documented in docs/compatibility.md. Maintainer release ordering is documented in docs/releasing.md.

Security vulnerabilities should be reported through the private process in SECURITY.md, not through a public issue.

Support The Project

If this Google News API Python client saves you time, consider sponsoring the project:

Sponsor ma2za on GitHub

Stars, bug reports, and focused pull requests also help maintain the project.

License

MIT License. See LICENSE.

Acknowledgments

URL decoding is based on the work of SSujitX/google-news-url-decoder.