### Setup GNews with Docker

Source: https://github.com/ranahaani/gnews/blob/master/README.md

Set up the GNews project locally using Docker. Ensure Docker and docker-compose are installed, configure the .env file with MongoDB credentials, and run the docker-compose command.

```shell
docker-compose up --build
```

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

### Async News Fetching Example

Source: https://github.com/ranahaani/gnews/blob/master/_autodocs/api-reference/gnews-client.md

Demonstrates how to fetch top news and technology news asynchronously using `asyncio` and the `GNews` client. Requires `asyncio` to be installed and configured.

```python
import asyncio
from gnews import GNews

async def fetch_news():
    gnews = GNews()
    top = await gnews.get_top_news_async()
    tech = await gnews.get_news_by_topic_async("TECHNOLOGY")
    return top, tech

articles_top, articles_tech = asyncio.run(fetch_news())
```

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

### Setup SearchApi Backend

Source: https://github.com/ranahaani/gnews/blob/master/docs/backends/searchapi.md

Get a free API key from searchapi.io and pass it to the GNews constructor. This snippet shows how to initialize GNews with your SearchApi key and perform a search.

```python
from gnews import GNews

g = GNews(searchapi_key="YOUR_SEARCHAPI_KEY", max_results=10)
articles = g.get_news("artificial intelligence")
```

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

### Setup GNews with Git Clone

Source: https://github.com/ranahaani/gnews/blob/master/README.md

Clone the GNews repository and set up a local development environment. This involves creating a virtual environment, activating it, and installing dependencies from requirements.txt.

```shell
git clone https://github.com/ranahaani/GNews.git
```

```shell
virtualenv venv
source venv/bin/activate  # MacOS/Linux
.\venv\Scripts\activate  # Windows
```

```shell
pip install -r requirements.txt
```

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

### Install GNews with Playwright for URL Resolution

Source: https://github.com/ranahaani/gnews/blob/master/README.md

Shows the command to install the GNews library with the optional Playwright extra for automatic URL resolution. Includes the one-time setup command for Playwright.

```shell
pip install gnews[playwright]
playwright install chromium  # one-time setup
```

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

### Development Install

Source: https://github.com/ranahaani/gnews/blob/master/docs/installation.md

Clone the GNews repository and install dependencies for development purposes.

```shell
git clone https://github.com/ranahaani/GNews.git
cd GNews
pip install -r requirements.txt
```

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

### Complete GNews Configuration Example

Source: https://github.com/ranahaani/gnews/blob/master/_autodocs/configuration.md

A comprehensive example showing how to combine various configuration options, including content, time filtering, results, network, retry, and backend settings, in a single GNews instance.

```python
from gnews import GNews
import datetime

gnews = GNews(
    # Content
    language="french",
    country="France",
    
    # Time filtering
    start_date=datetime.datetime(2024, 1, 1),
    end_date=datetime.datetime(2024, 12, 31),
    
    # Results
    max_results=50,
    exclude_websites=["reddit.com", "pinterest.com"],
    
    # Network
    proxy={"https": "http://proxy.example.com:8080"},
    
    # Retry
    max_retries=5,
    retry_backoff_base=1.5,
    retry_backoff_max=120.0,
    
    # Backend
    searchapi_key="YOUR_SEARCHAPI_KEY"
)
```

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

### Basic Installation

Source: https://github.com/ranahaani/gnews/blob/master/docs/installation.md

Install the GNews package using pip. Requires Python 3.10 or higher.

```shell
pip install gnews
```

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

### Install with Full Article Support

Source: https://github.com/ranahaani/gnews/blob/master/docs/installation.md

Install GNews with the 'fulltext' extra to enable `get_full_article()` functionality using trafilatura.

```shell
pip install gnews[fulltext]
```

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

### Install All Extras

Source: https://github.com/ranahaani/gnews/blob/master/docs/installation.md

Install GNews with both 'fulltext' and 'playwright' extras for complete functionality. Includes Playwright browser installation.

```shell
pip install "gnews[fulltext,playwright]"
playwright install chromium
```

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

### Clone Repository and Install Dependencies

Source: https://github.com/ranahaani/gnews/blob/master/docs/contributing.md

Clone the GNews repository and install the necessary Python dependencies. This is the first step to set up your local development environment.

```shell
git clone https://github.com/ranahaani/GNews.git
cd GNews
pip install -r requirements.txt
pip install pytest
```

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

### Install GNews Library

Source: https://github.com/ranahaani/gnews/blob/master/examples/tutorial.ipynb

Install the GNews library using pip. This command can be run in your terminal or a notebook cell.

```bash
!pip install gnews

```

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

### Install with Real URL Resolution

Source: https://github.com/ranahaani/gnews/blob/master/docs/installation.md

Install GNews with the 'playwright' extra to resolve Google News redirect URLs. This also requires a one-time Playwright browser installation.

```shell
pip install gnews[playwright]
playwright install chromium
```

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

### Install Pandas Library

Source: https://github.com/ranahaani/gnews/blob/master/examples/tutorial.ipynb

Installs the Pandas library, which is required for exporting news data to CSV format and converting it into a DataFrame.

```shell
!pip install pandas
```

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

### GNews CLI Commands

Source: https://github.com/ranahaani/gnews/blob/master/_autodocs/MANIFEST.txt

Documentation for the GNews command-line interface, including installation, subcommands, and usage examples.

```APIDOC
## GNews CLI Commands

### Description
The GNews library provides a command-line interface (CLI) for interacting with its news fetching capabilities directly from the terminal. This section covers installation, available commands, options, and usage examples.

### Installation
Instructions for installing GNews and verifying the CLI installation.

### Subcommands
- **gnews search**: Performs a general search for news articles.
- **gnews top**: Retrieves the top news articles.
- **gnews topic**: Fetches news articles filtered by a specific topic.
- **gnews site**: Retrieves news articles from a specified website.
- **gnews location**: Fetches news articles based on a geographical location.

### Options
- **Global Options**: Options applicable to all commands.
- **Per-command Options**: Options specific to each subcommand.
- **Output Formats**: Support for human-readable and JSON output.

### Usage Examples
```bash
# Search for articles about 'technology'
gnews search technology

# Get top news in JSON format
gnews top --output json

# Get news on 'business' topic for Canada
gnews topic business --country CA
```

### Exit Codes
Information on the exit codes returned by the CLI commands, indicating success or failure.
```

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

### CLI Usage Example

Source: https://github.com/ranahaani/gnews/blob/master/README.md

Demonstrates how to use GNews from the command line interface. This allows quick searches without writing Python code.

```bash
# Get top news for US
gnews --country US --topnews

# Search for 'AI' news
gnews --keyword "AI"

# Get news by topic 'Technology' for country 'IN'
gnews --topic "Technology" --country "IN"

# Get news by site 'reuters.com'
gnews --site "reuters.com"

# Get full article from URL
gnews --url "https://www.bbc.com/news/world-us-canada-67890123"

# Export results to CSV
gnews --keyword "Python" --export "python_news.csv"
```

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

### Verify GNews CLI Installation

Source: https://github.com/ranahaani/gnews/blob/master/_autodocs/api-reference/cli.md

Checks if the gnews CLI is installed and accessible by displaying its help message.

```bash
gnews --help
```

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

### Install GNews Package

Source: https://github.com/ranahaani/gnews/blob/master/README.md

Install the GNews package using pip. For full article text extraction, install with the 'fulltext' extra. For real article URL resolution, install with 'playwright' and run 'playwright install chromium'.

```shell
pip install gnews
```

```shell
pip install gnews[fulltext]
```

```shell
pip install gnews[playwright]
playwright install chromium
```

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

### Async Support Example

Source: https://github.com/ranahaani/gnews/blob/master/README.md

Utilize asynchronous capabilities for fetching news, which can improve performance in I/O-bound applications. Requires an async event loop.

```python
import asyncio
from gnews import GNews

async def main():
    gnews = GNews()
    # Get top news for US asynchronously
    json_response = await gnews.get_top_news_async('US')
    print(json_response)

if __name__ == '__main__':
    asyncio.run(main())
```

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

### Install vaderSentiment and Plotting Libraries

Source: https://github.com/ranahaani/gnews/blob/master/examples/tutorial.ipynb

Install the vaderSentiment library for sentiment analysis and matplotlib/seaborn for plotting. This is a prerequisite for performing sentiment analysis on news articles.

```shell
!pip install vaderSentiment matplotlib seaborn

```

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

### GNews SearchApi Article Data Example

Source: https://github.com/ranahaani/gnews/blob/master/README.md

An example of the JSON structure for an article obtained using the SearchApi backend, including fields like title, description, and iso_date.

```json
{
  "title": "OpenAI announces new model",
  "description": "Article snippet from SearchApi...",
  "published date": "2 hours ago",
  "iso_date": "2026-06-11T10:00:00Z",
  "url": "https://techcrunch.com/2026/06/11/openai-new-model",
  "publisher": "TechCrunch",
  "thumbnail": "data:image/jpeg;base64,...",
  "favicon": "data:image/png;base64,...",
  "rank": 1
}
```

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

### GNews Command Line Interface Examples

Source: https://github.com/ranahaani/gnews/blob/master/_autodocs/README.md

Demonstrates various ways to use the GNews command-line interface for searching, fetching top news, filtering by topic, site, and location.

```bash
gnews search "AI"
gnews top --country India --max 20 --json
gnews topic TECHNOLOGY
gnews site bbc.com
gnews location London
```

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

### Configure HTTP Proxy Settings

Source: https://github.com/ranahaani/gnews/blob/master/README.md

Define proxy settings for HTTP requests. This example shows how to configure an HTTP proxy.

```python
proxy = {
    'http': 'http://your_proxy_address',
}
```

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

### Get and Set Country

Source: https://github.com/ranahaani/gnews/blob/master/_autodocs/api-reference/gnews-client.md

Shows how to get and set the country for news headlines. The setter accepts full country names or codes, and invalid values are preserved.

```python
gnews = GNews()
print(gnews.country)  # "US"
gnews.country = "United Kingdom"
print(gnews.country)  # "GB"
```

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

### Get Finance News as JSON

Source: https://github.com/ranahaani/gnews/blob/master/_autodocs/api-reference/cli.md

Retrieves news articles for the 'FINANCE' topic and formats the output as JSON.

```bash
gnews topic FINANCE --json
```

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

### Configure HTTPS Proxy Settings

Source: https://github.com/ranahaani/gnews/blob/master/README.md

Define proxy settings for HTTPS requests. This example shows how to configure an HTTPS proxy.

```python
proxy = {
    'https': 'http://your_proxy_address',
}
```

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

### Get News by Site with GNews CLI

Source: https://github.com/ranahaani/gnews/blob/master/README.md

Demonstrates how to retrieve news from a specific website using the GNews CLI, with an option to limit results.

```shell
gnews site bbc.com
```

```shell
gnews site cnn.com --max 3
```

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

### Get News by Site

Source: https://github.com/ranahaani/gnews/blob/master/docs/reference/api.md

Fetch news articles from a particular website domain.

```python
articles = g.get_news_by_site("bbc.com")
```

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

### Get and Set Max Results

Source: https://github.com/ranahaani/gnews/blob/master/_autodocs/api-reference/gnews-client.md

Illustrates retrieving and setting the maximum number of results per query. Setting to a value less than or equal to 0 will raise an InvalidConfigError.

```python
gnews = GNews(max_results=50)
print(gnews.max_results)  # 50
gnews.max_results = 200
```

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

### Initialize GNews with Quality Filtering

Source: https://github.com/ranahaani/gnews/blob/master/_autodocs/configuration.md

Exclude specific websites from search results to filter out low-quality or unwanted sources. This example excludes Reddit, Pinterest, Instagram, and Twitter.

```python
from gnews import GNews

# Exclude low-quality sources
gnews = GNews(
    exclude_websites=["reddit.com", "pinterest.com", "instagram.com", "twitter.com"],
    max_results=30
)
```

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

### Get News by Topic with GNews CLI

Source: https://github.com/ranahaani/gnews/blob/master/README.md

Illustrates fetching news articles categorized by topic, with an option to specify the maximum number of results.

```shell
gnews topic TECHNOLOGY
```

```shell
gnews topic BUSINESS --max 5
```

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

### Get Top Headlines

Source: https://github.com/ranahaani/gnews/blob/master/_autodocs/api-reference/cli.md

Retrieves the top 10 news headlines for the default country (US) and language (English).

```bash
gnews top
```

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

### Use Premium Backend

Source: https://github.com/ranahaani/gnews/blob/master/_autodocs/README.md

Enable the premium backend for enhanced features or higher limits by providing your `searchapi_key` during client initialization.

```python
searchapi_key parameter
```

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

### Get Top Headlines in Spanish as JSON

Source: https://github.com/ranahaani/gnews/blob/master/_autodocs/api-reference/cli.md

Retrieves the top 15 news headlines in Spanish and formats the output as JSON.

```bash
gnews top --lang spanish --max 15 --json
```

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

### Fallback URL Example (No Playwright)

Source: https://github.com/ranahaani/gnews/blob/master/docs/usage/url-resolution.md

When Playwright is not installed or resolution fails, GNews returns the original Google redirect URL without raising an error.

```python
# Without gnews[playwright]:
print(articles[0]['url'])
```

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

### Get News by Location with GNews CLI

Source: https://github.com/ranahaani/gnews/blob/master/README.md

Shows how to fetch news articles based on a specified location using the GNews CLI, with an option to limit results.

```shell
gnews location Pakistan
```

```shell
gnews location India --max 5
```

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

### Get Full Article Details

Source: https://github.com/ranahaani/gnews/blob/master/README.md

Retrieve the full content of an article using its URL. This requires the article's direct link.

```python
from gnews import GNews

gnews = GNews()

# Get the full article from a URL
json_response = gnews.get_full_article('https://www.bbc.com/news/world-us-canada-67890123')

# Print the response
print(json_response)
```

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

### GNews Command Line Interface

Source: https://github.com/ranahaani/gnews/blob/master/_autodocs/README.md

This snippet shows examples of how to use the GNews package directly from the command line for various news-related tasks.

```APIDOC
## Command Line Interface

### Description
This section details the command-line interface (CLI) for the GNews package, enabling users to perform news searches and retrieve information directly from their terminal.

### Commands
- **`gnews search "<query>"`**: Searches for news articles related to the specified query.
- **`gnews top --country <country_code> --max <number> --json`**: Retrieves top news articles for a given country, with an option to limit the number of results and output in JSON format.
- **`gnews topic <topic>`**: Fetches news articles related to a specific topic.
- **`gnews site <domain>`**: Retrieves news articles from a specified website domain.
- **`gnews location <location>`**: Fetches news articles related to a specific geographical location.
```

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

### Get Gaming News from UK as JSON

Source: https://github.com/ranahaani/gnews/blob/master/_autodocs/api-reference/cli.md

Retrieves news articles for the 'GAMING' topic from the United Kingdom, limiting to 20 results and outputting as JSON.

```bash
gnews topic GAMING --country "United Kingdom" --max 20
```

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

### Get Top UK Headlines in JSON

Source: https://github.com/ranahaani/gnews/blob/master/_autodocs/api-reference/cli.md

Fetches the top news headlines from the United Kingdom, limits to 30 results, and exports them to a JSON file named 'uk_headlines.json'.

```bash
# Top headlines from UK in JSON format
gnews top --country "United Kingdom" --max 30 --json > uk_headlines.json
```

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

### Get Top Headlines with GNews CLI

Source: https://github.com/ranahaani/gnews/blob/master/README.md

Shows how to retrieve top news headlines using the GNews CLI, with an option to limit the number of results.

```shell
gnews top
```

```shell
gnews top --max 10
```

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

### Initialize GNews with Premium Backend

Source: https://github.com/ranahaani/gnews/blob/master/_autodocs/configuration.md

Utilize the SearchAPI for enhanced pagination and reliability by providing a searchapi_key. This enables features like paginated news retrieval.

```python
from gnews import GNews

# Use SearchAPI for pagination and reliability
gnews = GNews(
    searchapi_key="YOUR_SEARCHAPI_KEY",
    language="en",
    country="US",
    max_results=20
)

# Pagination now works
page1 = gnews.get_news("AI", page=1)
page2 = gnews.get_news("AI", page=2)
```

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

### JSON Output with GNews CLI

Source: https://github.com/ranahaani/gnews/blob/master/README.md

Illustrates how to get news search results in JSON format for pipe-friendly processing, including piping to Python's JSON tool.

```shell
gnews search "OpenAI" --json
```

```shell
gnews top --json | python3 -m json.tool
```

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

### URL Resolution Example

Source: https://github.com/ranahaani/gnews/blob/master/README.md

Resolve shortened or ambiguous URLs to their canonical form to ensure accurate article fetching. This is useful when dealing with various URL formats.

```python
from gnews import GNews

gnews = GNews()

# Resolve a URL
resolved_url = gnews.resolve_url('https://bit.ly/example-short-url')

# Print the resolved URL
print(resolved_url)
```

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

### Initialize GNews Client

Source: https://github.com/ranahaani/gnews/blob/master/docs/reference/api.md

Instantiate the GNews client with various configuration options. Default values are provided for most parameters.

```python
class GNews(
    language: str = "en",
    country: str = "US",
    max_results: int = 100,
    period: str | None = None,
    start_date: tuple | datetime | None = None,
    end_date: tuple | datetime | None = None,
    exclude_websites: list[str] | None = None,
    proxy: dict | None = None,
    searchapi_key: str | None = None,
    max_retries: int = 3,
    retry_backoff_base: float = 1.0,
    retry_backoff_max: float = 60.0,
)
```

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

### Initialize SearchApiBackend

Source: https://github.com/ranahaani/gnews/blob/master/_autodocs/api-reference/searchapi-backend.md

Initialize the SearchAPI backend with your SearchAPI.io API key. Ensure the api_key is not empty or None to avoid an InvalidConfigError.

```python
from gnews.backends.searchapi import SearchApiBackend

backend = SearchApiBackend("YOUR_SEARCHAPI_KEY")
```

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

### Initialize GNews with Proxy and Parameters

Source: https://github.com/ranahaani/gnews/blob/master/README.md

Initialize the GNews object with various parameters, including language, country, date ranges, result limits, excluded websites, and proxy settings.

```python
from gnews import GNews

# Initialize GNews with various parameters, including proxy
google_news = GNews(
    language='en',
    country='US',
    period='7d',
    start_date=None,
    end_date=None,
    max_results=10,
    exclude_websites=['yahoo.com', 'cnn.com'],
    proxy={
        'https': 'https://your_proxy_address'
    }
)
```

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

### Basic News Search with GNews

Source: https://github.com/ranahaani/gnews/blob/master/index.rst

Demonstrates how to initialize GNews and fetch news articles for a specific keyword. The first result is printed.

```python
from gnews import GNews

google_news = GNews()
pakistan_news = google_news.get_news('Pakistan')
print(pakistan_news[0])
```

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

### URL Resolution with and without Playwright

Source: https://github.com/ranahaani/gnews/blob/master/README.md

Illustrates the difference in article URLs obtained with and without the Playwright extra installed. When Playwright is installed, GNews resolves redirect URLs to real article URLs.

```python
from gnews import GNews

g = GNews(max_results=5)
articles = g.get_news("AI")

# With gnews[playwright] installed:
print(articles[0]['url'])  # https://www.politico.com/news/...

# Without gnews[playwright]:
print(articles[0]['url'])  # https://news.google.com/rss/articles/...
```

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

### Initialize GNews with Default Settings

Source: https://github.com/ranahaani/gnews/blob/master/_autodocs/configuration.md

Use this snippet to create a GNews instance with all default parameters. This includes English language, US country, and a maximum of 100 results.

```python
from gnews import GNews

# Use all defaults (English, US, 100 max results)
gnews = GNews()
```

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

### Initialize GNews with Advanced Filters

Source: https://github.com/ranahaani/gnews/blob/master/examples/tutorial.ipynb

Initialize the GNews object with parameters for language, country, maximum results, time period, and lists of websites to include or exclude. Replace the proxy with your actual proxy address if needed.

```python
from gnews import GNews

# Initialize with advanced parameters
google_news = GNews(
    language='en',
    country='US',
    max_results=10,
    period='7d',  # last 7 days
    exclude_websites=['yahoo.com','cnn.com'],
    include_websites=['bbc.com','techcrunch.com'],
    proxy='https://your_proxy_address:port'  # Replace with your proxy if needed
)

# Fetch news with multiple filters
tech_news = google_news.get_news('Artificial Intelligence')
df_tech = pd.DataFrame(tech_news)
df_tech.head()
```

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

### Get Top Headlines

Source: https://github.com/ranahaani/gnews/blob/master/docs/reference/api.md

Retrieve the current top news headlines.

```python
articles = g.get_top_news()
```

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

### Configure GNews with SearchAPI Key

Source: https://github.com/ranahaani/gnews/blob/master/_autodocs/configuration.md

Use an optional SearchAPI.io key to enable a premium backend for news searches, providing pagination and more reliable results. If no key is provided, the default free backend is used.

```python
from gnews import GNews

# Use free backend (default)
gnews = GNews()

# Use SearchAPI backend
gnews = GNews(searchapi_key="YOUR_SEARCHAPI_KEY")

# SearchAPI is automatically used for get_news() calls
articles = gnews.get_news("AI", page=2)
```

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

### Get News from India

Source: https://github.com/ranahaani/gnews/blob/master/_autodocs/api-reference/cli.md

Retrieves news articles geographically related to India.

```bash
gnews location India
```

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

### Get News from BBC

Source: https://github.com/ranahaani/gnews/blob/master/_autodocs/api-reference/cli.md

Retrieves news articles published by BBC (bbc.com).

```bash
gnews site bbc.com
```

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

### Import and Initialize GNews Client

Source: https://github.com/ranahaani/gnews/blob/master/examples/tutorial.ipynb

Import the GNews library and create an instance of the GNews client. This client object is used for all subsequent news fetching operations.

```python
from gnews import GNews
google_news = GNews()
google_news

```

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

### Get Technology News

Source: https://github.com/ranahaani/gnews/blob/master/_autodocs/api-reference/cli.md

Retrieves news articles categorized under the 'TECHNOLOGY' topic.

```bash
gnews topic TECHNOLOGY
```

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

### Basic Async News Fetch

Source: https://github.com/ranahaani/gnews/blob/master/docs/usage/async.md

Demonstrates how to fetch news articles asynchronously for a given query using `get_news_async`.

```python
import asyncio
from gnews import GNews

g = GNews(max_results=10)

articles = asyncio.run(g.get_news_async("artificial intelligence"))
```

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

### Get News by Location

Source: https://github.com/ranahaani/gnews/blob/master/docs/reference/api.md

Retrieve news articles for a specified city, state, or country.

```python
articles = g.get_news_by_location("Pakistan")
```

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

### SearchApiBackend Constructor

Source: https://github.com/ranahaani/gnews/blob/master/_autodocs/api-reference/searchapi-backend.md

Initializes the SearchAPI backend with your SearchAPI.io API key. This key is essential for authenticating requests to the SearchAPI.io service.

```APIDOC
## `__init__` Constructor

### Description
Initializes the SearchAPI backend with an API key.

### Method
`__init__(self, api_key: str)`

### Parameters
#### Path Parameters
- **api_key** (str) - Required - SearchAPI.io API key (required, cannot be empty).

### Raises
- `InvalidConfigError` if api_key is empty or None.

### Example
```python
from gnews.backends.searchapi import SearchApiBackend

backend = SearchApiBackend("YOUR_SEARCHAPI_KEY")
```
```

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

### Get News by Topic

Source: https://github.com/ranahaani/gnews/blob/master/docs/reference/api.md

Fetch news articles related to a specific major topic.

```python
articles = g.get_news_by_topic("TECHNOLOGY")
```

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

### Search News with GNews CLI

Source: https://github.com/ranahaani/gnews/blob/master/README.md

Demonstrates how to search for news articles using the GNews CLI with different query parameters.

```shell
gnews search "artificial intelligence"
```

```shell
gnews search "Pakistan" --lang ur --country PK --max 5
```

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

### Get News by Keyword

Source: https://github.com/ranahaani/gnews/blob/master/README.md

Search for news articles related to a specific keyword. The search is case-insensitive.

```python
from gnews import GNews

gnews = GNews()

# Get news about 'Python programming'
json_response = gnews.get_news_by_keyword('Python programming')

# Print the response
print(json_response)
```

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

### Initialize GNews with Parameters

Source: https://github.com/ranahaani/gnews/blob/master/index.rst

Initialize the GNews object with specific parameters like language, country, period, max results, excluded websites, and proxy. This is useful for setting up your news feed according to your preferences.

```python
google_news = GNews(language='en', country='US', period='7d', max_results=10, exclude_websites=['yahoo.com', 'cnn.com'],
                    proxy=proxy)
```

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

### Get Top Headlines from India

Source: https://github.com/ranahaani/gnews/blob/master/_autodocs/api-reference/cli.md

Retrieves the top 30 news headlines specifically from India.

```bash
gnews top --country India --max 30
```

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

### Initialize GNews with Network and Retry Options

Source: https://github.com/ranahaani/gnews/blob/master/_autodocs/configuration.md

Configure network settings for unreliable connections, including aggressive retries with backoff, proxy usage, or disabling retries entirely for manual handling.

```python
from gnews import GNews

# Aggressive retries for unreliable networks
gnews = GNews(
    max_retries=5,
    retry_backoff_base=0.5,  # Start with 0.5 second
    retry_backoff_max=30.0   # Cap at 30 seconds
)

# Use proxy
gnews = GNews(
    proxy={"https": "http://proxy.example.com:8080"},
    max_retries=3
)

# Disable retries (handle manually)
gnews = GNews(max_retries=0)
```

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

### Get CNN News as JSON

Source: https://github.com/ranahaani/gnews/blob/master/_autodocs/api-reference/cli.md

Retrieves news articles from CNN (cnn.com) and formats the output as JSON.

```bash
gnews site cnn.com --json
```

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

### Get News by Site Asynchronously

Source: https://github.com/ranahaani/gnews/blob/master/docs/reference/api.md

Asynchronous version of the `get_news_by_site` method for fetching news from a specific domain.

```python
articles = await g.get_news_by_site_async("bbc.com")
```

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

### Search Multiple Topics and Append to File

Source: https://github.com/ranahaani/gnews/blob/master/_autodocs/api-reference/cli.md

Iterates through a list of topics (TECHNOLOGY, BUSINESS, SPORTS), searches for news for each topic with a maximum of 5 results, and appends the output to 'all_news.txt'.

```bash
# Multiple searches
for topic in TECHNOLOGY BUSINESS SPORTS; do
  gnews topic "$topic" --max 5 >> all_news.txt
done
```

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

### Initialize GNews Client

Source: https://github.com/ranahaani/gnews/blob/master/_autodocs/api-reference/gnews-client.md

Instantiate the GNews client with various configuration options. You can specify language, country, result limits, date ranges, websites to exclude, proxy settings, and API keys for different backends. Retry parameters control how the client handles rate limiting.

```python
from gnews import GNews
import datetime

# Basic client with English and US
gnews = GNews()
```

```python
# Client with language and country customization
gnews = GNews(language="french", country="France")
```

```python
# Client with date range and retry configuration
gnews = GNews(
    language="en",
    country="US",
    max_results=50,
    start_date=datetime.datetime(2024, 1, 1),
    end_date=datetime.datetime(2024, 12, 31),
    exclude_websites=["pinterest.com", "instagram.com"],
    max_retries=5,
    retry_backoff_base=2.0
)
```

```python
# Client with proxy and SearchAPI backend
gnews = GNews(
    proxy={"https": "http://proxy.example.com:8080"},
    searchapi_key="YOUR_API_KEY"
)
```

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

### Get News by Location Asynchronously

Source: https://github.com/ranahaani/gnews/blob/master/docs/reference/api.md

Asynchronous version of the `get_news_by_location` method for fetching news by geographical location.

```python
articles = await g.get_news_by_location_async("Pakistan")
```

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

### Get News by Topic Asynchronously

Source: https://github.com/ranahaani/gnews/blob/master/docs/reference/api.md

Asynchronous version of the `get_news_by_topic` method for fetching news by a major topic.

```python
articles = await g.get_news_by_topic_async("TECHNOLOGY")
```

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

### GNews Python API Initialization and News Fetching

Source: https://github.com/ranahaani/gnews/blob/master/_autodocs/README.md

Initialize the GNews client and fetch news articles for a specific topic. Ensure necessary imports are included.

```python
from gnews import GNews, GNewsException, RateLimitError, InvalidConfigError, NetworkError

gnews = GNews()
articles = gnews.get_news("artificial intelligence")
```

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

### Get Top Headlines Asynchronously

Source: https://github.com/ranahaani/gnews/blob/master/docs/reference/api.md

Asynchronous version of the `get_top_news` method for retrieving current top headlines.

```python
articles = await g.get_top_news_async()
```

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

### get_full_article(url)

Source: https://github.com/ranahaani/gnews/blob/master/docs/reference/api.md

Extracts the full text content of an article from its URL. Requires the `gnews[fulltext]` extra to be installed.

```APIDOC
## get_full_article(url)

### Description
Extract full article text. Requires `pip install gnews[fulltext]`.

### Method
GET (implied)

### Parameters
#### Query Parameters
- **url** (str) - Required - The URL of the article to extract text from.

### Request Example
```python
article = g.get_full_article("https://example.com/article")
```

### Response
#### Success Response (200)
- **article** (dict) - A dictionary containing the article's `text` and `url`.

#### Errors
- **ImportError**: If `trafilatura` is not installed.
- **NetworkError**: If there is a failure during the network request.
```

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

### Configure Language and Country

Source: https://github.com/ranahaani/gnews/blob/master/_autodocs/README.md

Set the desired language and country for news retrieval during client initialization using the `language` and `country` constructor parameters.

```python
language, country parameters
```

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

### Access Article Images

Source: https://github.com/ranahaani/gnews/blob/master/index.rst

Get a set of image URLs associated with the article from the `images` attribute of the `article` object.

```python
article.images
```

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

### exclude_websites

Source: https://github.com/ranahaani/gnews/blob/master/_autodocs/api-reference/gnews-client.md

Get or set a list of websites to exclude from news results. Raises InvalidConfigError if the provided value is not a list.

```APIDOC
## exclude_websites

### Description
Get or set the list of excluded domains.

### Method
GET/SET

### Property
`exclude_websites`

### Returns
- `list[str]`: The current exclusion list.

### Raises
- `InvalidConfigError`: If set to a value that is not a list.

### Usage
```python
@property
def exclude_websites(self) -> list[str]
```

Setting requires a list; raises `InvalidConfigError` for other types.

```python
gnews.exclude_websites = ["reddit.com", "pinterest.com"]
print(gnews.exclude_websites)  # ["reddit.com", "pinterest.com"]
```
```

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

### Get Top News

Source: https://github.com/ranahaani/gnews/blob/master/README.md

Fetch the top news articles for a specific country. Ensure the country code is valid.

```python
from gnews import GNews

gnews = GNews()

# Get top headlines for the US
json_response = gnews.get_top_news('US')

# Print the response
print(json_response)
```

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

### Get Reuters News with Max Results

Source: https://github.com/ranahaani/gnews/blob/master/_autodocs/api-reference/cli.md

Retrieves news articles from Reuters (reuters.com), limiting the results to 30.

```bash
gnews site reuters.com --max 30
```

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

### Get Soccer News with Max Results

Source: https://github.com/ranahaani/gnews/blob/master/_autodocs/api-reference/cli.md

Retrieves news articles from the 'SOCCER' section, limiting the results to 15.

```bash
gnews topic SOCCER --max 15
```

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

### Async News Fetching with GNews

Source: https://github.com/ranahaani/gnews/blob/master/README.md

Demonstrates how to perform asynchronous news searches using the GNews library. This includes fetching a single topic and concurrently fetching multiple topics.

```python
import asyncio
from gnews import GNews

g = GNews(max_results=10)

# Single async query
articles = asyncio.run(g.get_news_async("AI"))

# Fetch multiple topics concurrently
async def main():
    ai, python, pakistan = await asyncio.gather(
        g.get_news_async("AI"),
        g.get_news_async("Python"),
        g.get_news_async("Pakistan"),
    )
    return ai, python, pakistan

asyncio.run(main())
```

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

### Use GNews from CLI

Source: https://github.com/ranahaani/gnews/blob/master/_autodocs/README.md

Interact with the GNews library from the command line using commands like `gnews search "query"`. This provides a convenient way to access news without writing Python code.

```bash
gnews search "query"
```

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

### get_full_article

Source: https://github.com/ranahaani/gnews/blob/master/_autodocs/api-reference/gnews-client.md

Fetches the complete text content of an article from its URL using Trafilatura. Requires the 'gnews[fulltext]' extra to be installed.

```APIDOC
## get_full_article

### Description
Fetch the complete text content of an article from its URL using Trafilatura.

### Method
```python
def get_full_article(self, url: str) -> dict
```

### Parameters
#### Path Parameters
- **url** (str) - Required - Direct article URL (not a Google News redirect).

### Returns
Dictionary with keys: "text" (article content), "url" (input URL).

### Raises
- `ImportError` if trafilatura is not installed. Install with: `pip install gnews[fulltext]`.
- `NetworkError` if the URL cannot be downloaded or text cannot be extracted.

### Example
```python
# Requires: pip install gnews[fulltext]
gnews = GNews()
articles = gnews.get_news("Python")
if articles:
    full = gnews.get_full_article(articles[0]["url"])
    print(full["text"])  # Full article content
    print(full["url"])   # Original URL
```
```

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

### Get News from Pakistan in Urdu as JSON

Source: https://github.com/ranahaani/gnews/blob/master/_autodocs/api-reference/cli.md

Retrieves news articles geographically related to Pakistan in Urdu, outputting as JSON.

```bash
gnews location Pakistan --lang urdu --json
```

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

### GNews Client Initialization

Source: https://github.com/ranahaani/gnews/blob/master/_autodocs/api-reference/gnews-client.md

Initializes the GNews client with various configuration options to customize news retrieval.

```APIDOC
## GNews Client Initialization

### Description
Initializes the GNews client with configuration options to fetch news articles.

### Method
```python
def __init__(
    self,
    language: str = "en",
    country: str = "US",
    max_results: int = 100,
    period: str | None = None,
    start_date: tuple | datetime.datetime | None = None,
    end_date: tuple | datetime.datetime | None = None,
    exclude_websites: list[str] | None = None,
    proxy: dict | None = None,
    searchapi_key: str | None = None,
    max_retries: int = 3,
    retry_backoff_base: float = 1.0,
    retry_backoff_max: float = 60.0,
) -> None
```

### Parameters
#### Initialization Parameters
- **language** (str) - Optional - ISO language code for results (e.g., "en", "fr", "ja"). Use full language names as keys (e.g., "english", "french").
- **country** (str) - Optional - ISO country code for headline regions (e.g., "US", "GB", "IN"). Use full country names as keys.
- **max_results** (int) - Optional - Maximum number of articles to return per request. Range: 1-10000. Requests >100 results use rolling date windows.
- **period** (str) - Optional - Time period filter (e.g., "7d" for last 7 days, "30d" for last 30 days). Ignored if start_date or end_date is set.
- **start_date** (tuple or datetime.datetime) - Optional - Earliest publication date. Format: (year, month, day) tuple or datetime.datetime object. Clears period if set.
- **end_date** (tuple or datetime.datetime) - Optional - Latest publication date. Format: (year, month, day) tuple or datetime.datetime object. Clears period if set.
- **exclude_websites** (list[str]) - Optional - List of domain names to exclude from results (e.g., ["bbc.com", "cnn.com"])
- **proxy** (dict) - Optional - Proxy settings as {protocol: address}, e.g., {"https": "http://proxy.example.com:8080"}.
- **searchapi_key** (str) - Optional - Optional SearchAPI.io API key to use the premium backend instead of free Google News RSS.
- **max_retries** (int) - Optional - Maximum retry attempts on HTTP 429 (rate limit) responses. Set to 0 to disable retries.
- **retry_backoff_base** (float) - Optional - Base seconds for exponential backoff: `min(retry_backoff_max, base * 2**attempt) + jitter(0, base)`.
- **retry_backoff_max** (float) - Optional - Maximum seconds any backoff wait can reach. Caps exponential growth.

### Raises
- `InvalidConfigError`: If max_results <= 0, max_retries < 0, or retry_backoff_base/max <= 0.

### Example
```python
from gnews import GNews
import datetime

# Basic client with English and US
gnews = GNews()

# Client with language and country customization
gnews = GNews(language="french", country="France")

# Client with date range and retry configuration
gnews = GNews(
    language="en",
    country="US",
    max_results=50,
    start_date=datetime.datetime(2024, 1, 1),
    end_date=datetime.datetime(2024, 12, 31),
    exclude_websites=["pinterest.com", "instagram.com"],
    max_retries=5,
    retry_backoff_base=2.0
)

# Client with proxy and SearchAPI backend
gnews = GNews(
    proxy={"https": "http://proxy.example.com:8080"},
    searchapi_key="YOUR_API_KEY"
)
```
```

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

### Search News with SearchApi Backend

Source: https://github.com/ranahaani/gnews/blob/master/README.md

Shows how to perform a news search using the GNews client configured with the SearchApi backend and print the first article.

```python
# All existing methods work as before
articles = google_news.get_news("artificial intelligence")
print(articles[0])
```

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

### Get News from London with Max Results

Source: https://github.com/ranahaani/gnews/blob/master/_autodocs/api-reference/cli.md

Retrieves news articles geographically related to London, limiting the results to 15.

```bash
gnews location London --max 15
```

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

### Initialize GNews with Filtering Parameters

Source: https://github.com/ranahaani/gnews/blob/master/docs/usage/filtering.md

Set filtering options like language, country, max results, period, date range, and excluded websites when creating a GNews object.

```python
from gnews import GNews

g = GNews(
    language="en",       # Language code (default: "en")
    country="US",        # Country code (default: "US")
    max_results=10,      # Max articles to return (default: 100)
    period="7d",         # Time period: 1h, 7d, 6m, 1y
    start_date=(2026, 1, 1),   # Or datetime object
    end_date=(2026, 6, 1),
    exclude_websites=["yahoo.com", "cnn.com"],
    proxy={"https": "https://your_proxy_address"},
)
```

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

### Extract Full Article Text

Source: https://github.com/ranahaani/gnews/blob/master/docs/reference/api.md

Extract the complete text content of an article from its URL. Requires the 'gnews[fulltext]' extra to be installed.

```python
article = g.get_full_article("https://example.com/article")
# {"text": "...", "url": "..."}
```

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

### Concurrent News Fetching

Source: https://github.com/ranahaani/gnews/blob/master/docs/usage/async.md

Shows how to fetch news for multiple queries simultaneously using `asyncio.gather` with `get_news_async`.

```python
import asyncio
from gnews import GNews

g = GNews(max_results=10)

async def main():
    ai, python, pakistan = await asyncio.gather(
        g.get_news_async("AI"),
        g.get_news_async("Python"),
        g.get_news_async("Pakistan"),
    )
    print(f"AI: {len(ai)} articles")
    print(f"Python: {len(python)} articles")
    print(f"Pakistan: {len(pakistan)} articles")

asyncio.run(main())
```