A robust Python client library for the Google News RSS feed API that provides both synchronous and asynchronous implementations with built-in rate limiting, caching, and error handling.
GoogleNewsClient for synchronous operationsAsyncGoogleNewsClient for async/await support# Install using Poetry
poetry add google-news-api
# Or clone and install from source
git clone https://github.com/ma2za/google-news-api.git
cd google-news-api
poetry install
pip install google-news-api
from google_news_api import GoogleNewsClient
# Initialize client with custom configuration
client = GoogleNewsClient(
language="en",
country="US",
requests_per_minute=60,
cache_ttl=300
)
try:
# Get top news by topic
world_news = client.top_news(topic="WORLD", max_results=5)
tech_news = client.top_news(topic="TECHNOLOGY", max_results=3)
# Search with date range
date_articles = client.search(
"Ukraine war",
after="2024-01-01",
before="2024-03-01",
max_results=5
)
# Search with relative time
recent_articles = client.search(
"climate change",
when="24h", # Last 24 hours
max_results=5
)
# Batch search multiple queries
batch_results = client.batch_search(
queries=["AI", "machine learning", "deep learning"],
when="7d", # Last 7 days
max_results=3
)
# Process results
for topic, articles in batch_results.items():
print(f"\nTop {topic} news:")
for article in articles:
print(f"- {article['title']} ({article['source']})")
print(f" Published: {article['published']}")
print(f" Summary: {article['summary'][:100]}...")
except Exception as e:
print(f"An error occurred: {e}")
finally:
# Clean up resources
del client
from google_news_api import AsyncGoogleNewsClient
import asyncio
async def main():
async with AsyncGoogleNewsClient(
language="en",
country="US",
requests_per_minute=60
) as client:
# Fetch multiple news categories concurrently
world_news = await client.top_news(topic="WORLD", max_results=3)
tech_news = await client.top_news(topic="TECHNOLOGY", max_results=3)
# Batch search with concurrent execution
batch_results = await client.batch_search(
queries=["AI", "machine learning", "deep learning"],
when="7d",
max_results=3
)
# Decode Google News URLs to original sources
for topic, articles in batch_results.items():
print(f"\nTop {topic} news:")
for article in articles:
original_url = await client.decode_url(article['link'])
print(f"- {article['title']} ({article['source']})")
print(f" Original URL: {original_url}")
if __name__ == "__main__":
asyncio.run(main())
The library provides extensive configuration options through the client initialization:
| Parameter | Description | Default | Example Values |
|---|---|---|---|
language | Two-letter language code (ISO 639-1) or language-country format | "en" | "en", "fr", "de", "en-US", "fr-FR" |
country | Two-letter country code (ISO 3166-1 alpha-2) | "US" | "US", "GB", "DE", "JP" |
requests_per_minute | Rate limit threshold for API requests | 60 | 30, 100, 120 |
cache_ttl | Cache duration in seconds for responses | 300 | 600, 1800, 3600 |
The top_news() method supports the following topics:
"WORLD" - World news"NATION" - National news"BUSINESS" - Business news"TECHNOLOGY" - Technology news"ENTERTAINMENT" - Entertainment news"SPORTS" - Sports news"SCIENCE" - Science news"HEALTH" - Health newsThe library supports two types of time-based search:
Date Range Search
after and before parametersYYYY-MM-DDafter="2024-01-01", before="2024-03-01"Relative Time Search
when parameter"1h" to "101h""7d", "30d")after/beforewhen="24h" for last 24 hoursEach article in the results contains the following fields:
title: Article titlelink: Google News article URLpublished: Publication date and timesummary: Article summary/descriptionsource: News source nameThe library provides specific exceptions for different error scenarios:
from google_news_api.exceptions import (
ConfigurationError, # Invalid client configuration
ValidationError, # Invalid parameters
HTTPError, # Network or server issues
RateLimitError, # Rate limit exceeded
ParsingError # RSS feed parsing errors
)
try:
articles = client.search("technology")
except RateLimitError as e:
print(f"Rate limit exceeded. Retry after {e.retry_after} seconds")
except HTTPError as e:
print(f"HTTP error {e.status_code}: {str(e)}")
except ValidationError as e:
print(f"Invalid parameters: {str(e)}")
except Exception as e:
print(f"Unexpected error: {str(e)}")
async with) for async clientsrequests_per_minute based on your requirements# Clone the repository
git clone https://github.com/ma2za/google-news-api.git
cd google-news-api
# Install development dependencies
poetry install --with dev
# Set up pre-commit hooks
pre-commit install
# Run tests with Poetry
poetry run pytest
# Run tests with coverage
poetry run pytest --cov=google_news_api
# Run pre-commit on all files
pre-commit run --all-files
git checkout -b feature/amazing-feature)poetry run pytest and poetry run flake8)git commit -m 'Add amazing feature')git push origin feature/amazing-feature)This project is licensed under the MIT License - see the LICENSE file for details.
Paolo Mazza (mazzapaolo2019@gmail.com)
For issues, feature requests, or questions:
The library supports two types of time-based search:
Use after and before parameters to search within a specific date range:
articles = client.search(
"Ukraine war",
after="2024-01-01", # Start date (YYYY-MM-DD)
before="2024-03-01", # End date (YYYY-MM-DD)
max_results=5
)
Use the when parameter for relative time searches:
# Last hour
articles = client.search("climate change", when="1h")
# Last 24 hours
articles = client.search("climate change", when="24h")
# Last 7 days
articles = client.search("climate change", when="7d")
Notes:
after/before) must be in YYYY-MM-DD formatwhen) supports:
when parameter cannot be used together with after or beforeFAQs
Unknown package
We found that google-news-api demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Vite releases Rolldown-Vite, a Rust-based bundler preview offering faster builds and lower memory usage as a drop-in replacement for Vite.
Research
Security News
A malicious npm typosquat uses remote commands to silently delete entire project directories after a single mistyped install.
Research
Security News
Malicious PyPI package semantic-types steals Solana private keys via transitive dependency installs using monkey patching and blockchain exfiltration.