### Get Stories by Topic

Source: https://github.com/kotartemiy/pygooglenews/blob/master/README.md

Fetch news articles for a specific topic. Ensure the topic is one of the supported categories like 'BUSINESS', 'TECHNOLOGY', etc.

```python
business = gn.topic_headlines('business')
```

```python
business = gn.topic_headlines('BUSINESS', proxies=None, scraping_bee = None)
```

--------------------------------

### Get Geolocation Headlines with Specific Language/Country

Source: https://github.com/kotartemiy/pygooglenews/blob/master/README.md

Initialize GoogleNews with a specific language and country, then retrieve geolocation-specific headlines. This example shows fetching news for Kyiv, Ukraine.

```python
gn = GoogleNews('uk', 'UA')
kyiv = gn.geo_headlines('kyiv', proxies=None, scraping_bee = None)
# or 
kyiv = gn.geo_headlines('kiev', proxies=None, scraping_bee = None)
# or
kyiv = gn.geo_headlines('киев', proxies=None, scraping_bee = None)
# or
kyiv = gn.geo_headlines('Київ', proxies=None, scraping_bee = None)
```

--------------------------------

### GET Top Stories

Source: https://github.com/kotartemiy/pygooglenews/blob/master/README.md

Fetches the top news stories for the configured country and language.

```APIDOC
## GET top_news()

### Description
Returns the top stories for the selected country and language defined in the GoogleNews instance.

### Parameters
#### Request Body
- **proxies** (dict) - Optional - Proxy settings
- **scraping_bee** (str) - Optional - ScrapingBee API key

### Response
- **feed** (FeedParserDict) - The parsed feed object
- **entries** (list) - List of articles found
```

--------------------------------

### Get Top News Stories

Source: https://github.com/kotartemiy/pygooglenews/blob/master/README.md

Retrieve the top news headlines for the configured language and country. The result includes feed information and a list of articles.

```python
top = gn.top_news()
```

```python
top = gn.top_news(proxies=None, scraping_bee = None)
```

--------------------------------

### Search Stories by Query

Source: https://github.com/kotartemiy/pygooglenews/blob/master/README.md

Perform a search for articles mentioning specific keywords, with options to exclude terms and specify a time range. For example, search for 'MSFT' and exclude 'AAPL' within the last 6 months.

```python
# search for the best matching articles that mention MSFT and 
# do not mention AAPL (over the past 6 month
search = gn.search('MSFT -APPL', when = '6m')
```

--------------------------------

### GET Topic Headlines

Source: https://github.com/kotartemiy/pygooglenews/blob/master/README.md

Fetches news headlines based on a specific topic.

```APIDOC
## GET topic_headlines()

### Description
Returns news headlines for a specific topic. Supported topics include WORLD, NATION, BUSINESS, TECHNOLOGY, ENTERTAINMENT, SCIENCE, SPORTS, HEALTH, or a custom topic ID.

### Parameters
#### Request Body
- **topic** (string) - Required - The topic name or topic ID
- **proxies** (dict) - Optional - Proxy settings
- **scraping_bee** (str) - Optional - ScrapingBee API key
```

--------------------------------

### GET Geolocation Headlines

Source: https://github.com/kotartemiy/pygooglenews/blob/master/README.md

Fetches news headlines for a specific geographic location.

```APIDOC
## GET geo_headlines()

### Description
Returns news headlines related to a specific geographic location.

### Parameters
#### Request Body
- **geo** (string) - Required - The location name
- **proxies** (dict) - Optional - Proxy settings
- **scraping_bee** (str) - Optional - ScrapingBee API key
```

--------------------------------

### Get Geolocation Specific Stories

Source: https://github.com/kotartemiy/pygooglenews/blob/master/README.md

Retrieve news headlines for a specified location. The library attempts to find relevant news based on the provided city name.

```python
headquaters = gn.geo_headlines('San Fran')
```

--------------------------------

### Get Topic Headlines using Topic ID

Source: https://github.com/kotartemiy/pygooglenews/blob/master/README.md

Fetch news articles using a specific topic ID, often found in Google News URLs. This method is useful for accessing niche or dynamically generated topics.

```python
from pygooglenews import GoogleNews

gn = GoogleNews()
covid = gn.topic_headlines('CAAqIggKIhxDQkFTRHdvSkwyMHZNREZqY0hsNUVnSmxiaWdBUAE')
```

--------------------------------

### Initialize GoogleNews

Source: https://github.com/kotartemiy/pygooglenews/blob/master/README.md

Import the GoogleNews class and create a default instance. This sets up the client for fetching news.

```python
from pygooglenews import GoogleNews

gn = GoogleNews()
```

--------------------------------

### Initialize GoogleNews Client

Source: https://context7.com/kotartemiy/pygooglenews/llms.txt

Configure the client with specific language and country parameters to define the regional news source.

```python
from pygooglenews import GoogleNews

# Default initialization (English, United States)
gn = GoogleNews()

# Custom language and country
gn_ukraine = GoogleNews(lang='uk', country='UA')
gn_german = GoogleNews(lang='de', country='DE')
gn_french = GoogleNews(lang='fr', country='FR')

# The client is now ready to fetch news
print(f"Configured for: {gn.lang}-{gn.country}")
# Output: Configured for: en-US
```

--------------------------------

### Using ScrapingBee with pygooglenews

Source: https://github.com/kotartemiy/pygooglenews/blob/master/README.md

Demonstrates how to initialize GoogleNews and use the top_news function with a ScrapingBee API key. Ensure you replace the fake API key with your actual key.

```python
gn = GoogleNews()

# it's a fake API key, do not try to use it
gn.top_news(scraping_bee = 'I5SYNPRFZI41WHVQWWUT0GNXFMO104343E7CXFIISR01E2V8ETSMXMJFK1XNKM7FDEEPUPRM0FYAHFF5')
```

--------------------------------

### Initialize GoogleNews with Language and Country

Source: https://github.com/kotartemiy/pygooglenews/blob/master/README.md

Instantiate the GoogleNews class with specific language and country codes. This allows for region-specific news fetching.

```python
from pygooglenews import GoogleNews
# default GoogleNews instance
gn = GoogleNews(lang = 'en', country = 'US')
```

--------------------------------

### GoogleNews Class Initialization

Source: https://github.com/kotartemiy/pygooglenews/blob/master/README.md

Initializes the GoogleNews client with specific language and country settings.

```APIDOC
## GoogleNews Class Initialization

### Description
Initializes the GoogleNews client. This is required before calling any other functions.

### Parameters
#### Request Body
- **lang** (string) - Required - Language code (e.g., 'en')
- **country** (string) - Required - Country code (e.g., 'US')

### Request Example
```python
from pygooglenews import GoogleNews
gn = GoogleNews(lang = 'en', country = 'US')
```
```

--------------------------------

### Configure HTTP/HTTPS proxies

Source: https://context7.com/kotartemiy/pygooglenews/llms.txt

Pass a dictionary of proxy settings to any request method to avoid IP blocking. Supports standard proxy formats including those with authentication.

```python
from pygooglenews import GoogleNews

gn = GoogleNews()

# Single proxy configuration
proxies = {'https': '34.91.135.38:80'}

# Use proxy with any function
top = gn.top_news(proxies=proxies)
business = gn.topic_headlines('BUSINESS', proxies=proxies)
sf = gn.geo_headlines('San Francisco', proxies=proxies)
search = gn.search('technology', proxies=proxies)

# Multiple proxy formats
proxy_with_auth = {
    'http': 'http://user:password@proxy-server:8080',
    'https': 'https://user:password@proxy-server:8080'
}

results = gn.search('AI news', proxies=proxy_with_auth)
print(f"Retrieved {len(results['entries'])} articles via proxy")
```

--------------------------------

### Configure HTTP/HTTPS proxies for GoogleNews

Source: https://github.com/kotartemiy/pygooglenews/blob/master/README.md

Pass a dictionary of proxies to the GoogleNews methods to route requests through specific servers.

```python
gn = GoogleNews()

gn.top_news(proxies = {'https':'34.91.135.38:80'})
```

--------------------------------

### Perform a Boolean OR search

Source: https://github.com/kotartemiy/pygooglenews/blob/master/README.md

Initializes the GoogleNews client and executes a search query using boolean operators.

```python
from pygooglenews import GoogleNews

gn = GoogleNews()

s = gn.search('boeing OR airbus')

print(s['feed'].title)
```

--------------------------------

### Integrate ScrapingBee API

Source: https://context7.com/kotartemiy/pygooglenews/llms.txt

Use ScrapingBee for automatic proxy rotation in production. Note that proxies and scraping_bee cannot be used simultaneously in the same request.

```python
from pygooglenews import GoogleNews

gn = GoogleNews()

# Your ScrapingBee API key
SCRAPINGBEE_KEY = 'YOUR_API_KEY_HERE'

# Use ScrapingBee with any function
top = gn.top_news(scraping_bee=SCRAPINGBEE_KEY)
business = gn.topic_headlines('BUSINESS', scraping_bee=SCRAPINGBEE_KEY)
geo = gn.geo_headlines('London', scraping_bee=SCRAPINGBEE_KEY)
search = gn.search('fintech', scraping_bee=SCRAPINGBEE_KEY)

# Note: Cannot use both proxies and scraping_bee simultaneously
# This will raise an exception:
# gn.top_news(proxies={'https': 'proxy:8080'}, scraping_bee=SCRAPINGBEE_KEY)

print(f"Retrieved {len(top['entries'])} top stories via ScrapingBee")
```

--------------------------------

### Fetch Topic Headlines

Source: https://context7.com/kotartemiy/pygooglenews/llms.txt

Retrieve news articles by standard category or custom topic ID.

```python
from pygooglenews import GoogleNews

gn = GoogleNews()

# Fetch news by standard topic
business = gn.topic_headlines('BUSINESS')
print(f"Business news count: {len(business['entries'])}")

tech = gn.topic_headlines('TECHNOLOGY')
sports = gn.topic_headlines('SPORTS')
health = gn.topic_headlines('HEALTH')
science = gn.topic_headlines('SCIENCE')
entertainment = gn.topic_headlines('ENTERTAINMENT')
world = gn.topic_headlines('WORLD')
nation = gn.topic_headlines('NATION')

# Process topic articles
for entry in business['entries'][:5]:
    print(f"{entry.title}")
    print(f"  Source: {entry.source.title if hasattr(entry, 'source') else 'N/A'}")
    print(f"  Link: {entry.link}")

# Custom topic using Google News topic ID
# Extract from URL: https://news.google.com/topics/CAAqIggKIhxDQkFTRHdvSkwyMHZNREZqY0hsNUVnSmxiaWdBUAE?...
covid_topic_id = 'CAAqIggKIhxDQkFTRHdvSkwyMHZNREZqY0hsNUVnSmxiaWdBUAE'
try:
    covid = gn.topic_headlines(covid_topic_id)
    print(f"COVID news: {len(covid['entries'])} articles")
except Exception as e:
    print(f"Topic not available: {e}")
```

--------------------------------

### Access response structure

Source: https://context7.com/kotartemiy/pygooglenews/llms.txt

Parse the returned dictionary to access feed metadata and article entries, including nested sub-articles.

```python
from pygooglenews import GoogleNews

gn = GoogleNews()
results = gn.top_news()

# Feed metadata (FeedParserDict)
feed = results['feed']
print(f"Feed Title: {feed.title}")
print(f"Feed Link: {feed.link}")
print(f"Feed Language: {feed.get('language', 'N/A')}")

# Entries list - parsed articles
entries = results['entries']
print(f"Total articles: {len(entries)}")

# Article structure
if entries:
    article = entries[0]
    print(f"\nFirst article:")
    print(f"  title: {article.title}")
    print(f"  link: {article.link}")
    print(f"  published: {article.published}")
    print(f"  published_parsed: {article.published_parsed}")
    print(f"  summary: {article.get('summary', 'N/A')[:100]}...")

    # Sub-articles (related news in same cluster)
    sub_articles = article.get('sub_articles', [])
    print(f"  sub_articles count: {len(sub_articles)}")

    for sub in sub_articles[:3]:
        print(f"    - {sub['title']}")
        print(f"      URL: {sub['url']}")
        print(f"      Publisher: {sub['publisher']}")
```

--------------------------------

### Search Google News with parameters

Source: https://github.com/kotartemiy/pygooglenews/blob/master/README.md

Defines the signature for the search method, which supports query helpers, time ranges, and date filtering.

```python
gn.search(query: str, helper = True, when = None, from_ = None, to_ = None, proxies=None, scraping_bee=None)
```

--------------------------------

### Retrieve Geo-Specific Headlines

Source: https://context7.com/kotartemiy/pygooglenews/llms.txt

Fetch news articles for a specific geographic location, supporting multiple languages and proxy configurations.

```python
from pygooglenews import GoogleNews

# US news client
gn = GoogleNews(lang='en', country='US')

# Fetch news by location (various formats work)
sf_news = gn.geo_headlines('San Francisco')
la_news = gn.geo_headlines('Los Angeles')
nyc_news = gn.geo_headlines('New York')

print(f"San Francisco news: {sf_news['feed'].title}")
# Output: San Francisco news: San Francisco - Latest - Google News

for entry in sf_news['entries'][:3]:
    print(f"- {entry.title}")

# Ukrainian news client - location names in multiple languages work
gn_ua = GoogleNews(lang='uk', country='UA')

# All these return the same Kyiv news feed
kyiv_en = gn_ua.geo_headlines('kyiv')
kyiv_alt = gn_ua.geo_headlines('kiev')
kyiv_ru = gn_ua.geo_headlines('киев')
kyiv_ua = gn_ua.geo_headlines('Київ')

print(f"Kyiv news feed: {kyiv_en['feed'].title}")
# Output: Kyiv news feed: Київ - Останні - Google Новини

# With proxy support
geo_proxied = gn.geo_headlines('Tokyo', proxies={'https': 'your-proxy:8080'})
```

--------------------------------

### Perform advanced search queries

Source: https://github.com/kotartemiy/pygooglenews/blob/master/README.md

Use the search method with Google search operators to filter results by keywords, titles, and timeframes.

```python
from pygooglenews import GoogleNews

gn = GoogleNews()

s = gn.search('boeing -airbus')

print(s['feed'].title)
# "boeing -airbus" - Google News
```

```python
from pygooglenews import GoogleNews

gn = GoogleNews()

s = gn.search('intitle:boeing')

print(s['feed'].title)
# "intitle:boeing" - Google News
```

```python
from pygooglenews import GoogleNews

gn = GoogleNews()

s = gn.search('intitle:boeing', when = '1h')

print(s['feed'].title)
# "intitle:boeing when:1h" - Google News
```

```python
from pygooglenews import GoogleNews

gn = GoogleNews()

s = gn.search('boeing OR airbus', when = '1h')

print(s['feed'].title)
# "boeing AND airbus when:1h" - Google News
```

--------------------------------

### Perform Google News searches

Source: https://context7.com/kotartemiy/pygooglenews/llms.txt

Execute full-text searches with support for time ranges, date filtering, and advanced query operators. The helper parameter is enabled by default to auto-escape URLs.

```python
from pygooglenews import GoogleNews

gn = GoogleNews()

# Basic search
results = gn.search('artificial intelligence')
print(f"Found {len(results['entries'])} articles")

# Search with time range (h=hours, d=days, m=months)
recent = gn.search('bitcoin', when='1h')  # Last hour
daily = gn.search('bitcoin', when='24h')  # Last 24 hours
weekly = gn.search('bitcoin', when='7d')  # Last 7 days
monthly = gn.search('bitcoin', when='1m')  # Last month

# Search with date range
dated = gn.search('tesla earnings', from_='2024-01-01', to_='2024-03-31')

# Exclude terms with minus operator
filtered = gn.search('MSFT -AAPL', when='6m')

# Boolean OR search
combined = gn.search('boeing OR airbus')
print(f"Feed: {combined['feed'].title")
# Output: Feed: "boeing OR airbus" - Google News

# Title-specific search
title_search = gn.search('intitle:boeing', when='1h')

# Phrase search (exact match)
phrase = gn.search('"climate change summit"')

# Advanced query operators
allintext = gn.search('allintext:renewable energy solar')
allintitle = gn.search('allintitle:AI startup funding')
inurl = gn.search('inurl:tech')

# Disable URL helper for custom queries
custom = gn.search('custom+query+here', helper=False)

# Process search results
for entry in results['entries'][:5]:
    print(f"Title: {entry.title}")
    print(f"Published: {entry.published}")
    print(f"Link: {entry.link}")
    if entry.get('sub_articles'):
        print(f"Related: {len(entry['sub_articles'])} articles")
    print("---")
```

--------------------------------

### Retrieve Top News Stories

Source: https://context7.com/kotartemiy/pygooglenews/llms.txt

Fetch top stories from the Google News main page. Supports optional proxy configuration and ScrapingBee API integration.

```python
from pygooglenews import GoogleNews

gn = GoogleNews()

# Fetch top news stories
top = gn.top_news()

# Access feed metadata
print(f"Feed title: {top['feed'].title}")
# Output: Feed title: Top stories - Google News

# Iterate through articles
for entry in top['entries'][:3]:
    print(f"Title: {entry.title}")
    print(f"Link: {entry.link}")
    print(f"Published: {entry.published}")
    # Sub-articles are related news stories
    if entry.get('sub_articles'):
        print(f"Related articles: {len(entry['sub_articles'])}")
        for sub in entry['sub_articles'][:2]:
            print(f"  - {sub['title']} ({sub['publisher']})")
    print("---")

# Using with proxy
top_with_proxy = gn.top_news(proxies={'https': '34.91.135.38:80'})

# Using with ScrapingBee API
top_with_scraping = gn.top_news(scraping_bee='YOUR_SCRAPINGBEE_API_KEY')
```

--------------------------------

### Accessing Feed Title for Geolocation News

Source: https://github.com/kotartemiy/pygooglenews/blob/master/README.md

After fetching geolocation news, you can access the title of the news feed using the 'feed' attribute of the returned object.

```python
geo['feed'].title
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.