### Install serpapi-python

Source: https://github.com/serpapi/serpapi-python/blob/master/docs/index.md

Install the library using pip. Python 3.6+ is required.

```bash
pip install serpapi
```

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

### Install and Run Tests

Source: https://github.com/serpapi/serpapi-python/blob/master/_autodocs/README.md

Install the package with test dependencies and run the test suite using pytest. Ensure the API_KEY environment variable is set for test fixtures.

```bash
pip install -e ".[test]"
pytest
```

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

### Python Example: Fetching and Filtering Locations

Source: https://github.com/serpapi/serpapi-python/blob/master/_autodocs/endpoints.md

This Python snippet shows how to initialize the SerpApi client and retrieve all supported locations or filter them by a query string and limit. It also includes an example of iterating through the results.

```python
import serpapi

client = serpapi.Client(api_key="your_api_key")

# Get all locations
all_locations = client.locations()

# Filter by substring
austin_locations = client.locations(q="Austin", limit=10)

for loc in austin_locations:
    print(f"{loc['name']} - {loc['country_code']}")
```

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

### Access Package Version

Source: https://github.com/serpapi/serpapi-python/blob/master/_autodocs/modules-and-imports.md

Import the serpapi package and print its __version__ attribute to get the installed version.

```python
import serpapi

print(serpapi.__version__)  # "1.0.2"
```

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

### Quick Start: Initialize Client and Perform Search

Source: https://github.com/serpapi/serpapi-python/blob/master/_autodocs/00-START-HERE.md

This snippet demonstrates how to initialize the SerpApi client with an API key, perform a search query, and access the organic results. It also shows how to paginate through the search results.

```python
import serpapi

# Create a client
client = serpapi.Client(api_key="your_api_key")

# Search
results = client.search(q="coffee", location="Austin, Texas")

# Access results
for result in results.get("organic_results", []):
    print(result["title"])

# Paginate
for page in results.yield_pages(max_pages=3):
    print(f"Page {page['search_metadata']['id']}")
```

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

### Retrieve Archived Search using Python Client

Source: https://github.com/serpapi/serpapi-python/blob/master/_autodocs/endpoints.md

This example demonstrates how to perform an initial search, get its ID, and then retrieve the archived results using the search ID. The archived results have the same structure as fresh search results.

```python
import serpapi

client = serpapi.Client(api_key="your_api_key")

# Perform initial search
results = client.search(q="coffee")
search_id = results["search_metadata"]["id"]

# Later, retrieve from archive
archived = client.search_archive(search_id=search_id)

# Same structure as fresh search
print(archived["search_metadata"]["id"])  # Same ID as original
```

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

### Get Account Information

Source: https://github.com/serpapi/serpapi-python/blob/master/_autodocs/quick-reference.md

Fetch account details like plan name and monthly searches used. Also demonstrates retrieving available locations and filtering them.

```python
# Get account info
account = client.account()
print(account["plan_name"])
print(account["monthly_searches_used"])

# Get locations
locations = client.locations()

# Filter locations
austin_locs = client.locations(q="Austin", limit=10)
```

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

### Set SERPAPI_KEY Environment Variable

Source: https://github.com/serpapi/serpapi-python/blob/master/_autodocs/quick-reference.md

Set the SERPAPI_KEY environment variable for authentication. Examples are provided for Linux/macOS, Windows CMD, and PowerShell.

```bash
# Linux/macOS
export SERPAPI_KEY=your_actual_key
```

```cmd
# Windows CMD
set SERPAPI_KEY=your_actual_key
```

```powershell
# Windows PowerShell
$env:SERPAPI_KEY="your_actual_key"
```

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

### SerpResults.__repr__

Source: https://github.com/serpapi/serpapi-python/blob/master/_autodocs/api-reference/serpresults.md

Returns a pretty-printed JSON representation of the results, with syntax highlighting if Pygments is installed.

```APIDOC
## Special Method: `__repr__`

Returns a pretty-printed JSON representation of the results (if Pygments is installed, with syntax highlighting).

```python
def __repr__(self) -> str
```

### Example

```python
results = client.search(q="coffee")
print(results)  # Nicely formatted JSON output
```
```

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

### Paginate All Available Search Results

Source: https://github.com/serpapi/serpapi-python/blob/master/_autodocs/configuration.md

This example shows how to iterate through all available pages of search results using the `yield_pages` method without specifying a `max_pages` limit.

```python
# Iterate through all available pages (up to default 1000)
page_count = 0
for page in results.yield_pages():
    page_count += 1
    # Process page...

print(f"Total pages: {page_count}")
```

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

### Execute GET Request with HTTPClient

Source: https://github.com/serpapi/serpapi-python/blob/master/_autodocs/api-reference/http-client.md

Use the `request` method to perform a GET request to a SerpApi endpoint. The API key is automatically injected, and the response status code is checked by default.

```python
from serpapi.http import HTTPClient

http_client = HTTPClient(api_key="your_api_key", timeout=10)

# Execute a GET request to /search
response = http_client.request(
    "GET",
    "/search",
    params={"q": "coffee", "engine": "google"}
)
print(response.status_code)
print(response.json())
```

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

### Using Module-Level Functions for Search Operations

Source: https://github.com/serpapi/serpapi-python/blob/master/_autodocs/modules-and-imports.md

Utilize convenience functions directly from the serpapi module for common tasks like searching, retrieving archived results, getting location suggestions, and accessing account information. These functions are bound to a singleton unauthenticated client.

```python
import serpapi

results = serpapi.search(q="coffee", api_key="...")
archived = serpapi.search_archive(search_id="...", api_key="...")
locations = serpapi.locations(api_key="...")
account_info = serpapi.account(api_key="...")
```

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

### Paginate Search Results with Max Pages

Source: https://github.com/serpapi/serpapi-python/blob/master/_autodocs/configuration.md

This example demonstrates how to iterate through a limited number of pages from search results using the `yield_pages` method with a `max_pages` argument.

```python
import serpapi

client = serpapi.Client(api_key="your_api_key")
results = client.search(q="coffee")

# Iterate through at most 5 pages
for page in results.yield_pages(max_pages=5):
    print(f"Page has {len(page.get('organic_results', []))} results")
```

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

### Google Search Pagination

Source: https://github.com/serpapi/serpapi-python/blob/master/_autodocs/configuration.md

Implement pagination to retrieve subsequent pages of search results. Specify the 'start' and 'num' parameters to control the offset and number of results per page.

```python
results = client.search(q="coffee", start=10, num=10)
```

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

### Google Search with Error Handling

Source: https://github.com/serpapi/serpapi-python/blob/master/README.md

Perform a Google search for 'coffee' with a specified timeout and includes error handling for HTTPError and TimeoutError. This example demonstrates how to catch and respond to common request issues.

```python
import os
import serpapi

# A default timeout can be set here.
client = serpapi.Client(api_key=os.getenv("API_KEY"), timeout=10)

try:
    results = client.search({
        'engine': 'google',
        'q': 'coffee',
    })
except serpapi.HTTPError as e:
    if e.status_code == 401: # Invalid API key
        print(e.error) # "Invalid API key. Your API key should be here: https://serpapi.com/manage-api-key"
    elif e.status_code == 400: # Missing required parameter
        pass
    elif e.status_code == 429: # Exceeds the hourly throughput limit OR account run out of searches
        pass
except serpapi.TimeoutError as e:
    # Handle timeout
    print(f"The request timed out: {e}")
```

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

### Client Class Methods

Source: https://github.com/serpapi/serpapi-python/blob/master/_autodocs/INDEX.md

Reference for the public methods of the Client class, used for executing searches, retrieving archived searches, getting supported locations, and accessing account information.

```APIDOC
## Client Class Methods

### `search()`

**Description:** Executes a search query using the SerpApi service.

### `search_archive()`

**Description:** Retrieves previously archived search results.

### `locations()`

**Description:** Fetches a list of supported geographical locations for searches.

### `account()`

**Description:** Retrieves account-related information.
```

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

### Initialize SerpApi Client with API Key

Source: https://github.com/serpapi/serpapi-python/blob/master/_autodocs/README.md

Demonstrates how to retrieve your SerpApi key from environment variables and initialize the SerpApi client.

```python
import os
import serpapi

api_key = os.getenv("SERPAPI_KEY")
client = serpapi.Client(api_key=api_key)
```

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

### Basic SerpApi Search and Pagination

Source: https://github.com/serpapi/serpapi-python/blob/master/_autodocs/README.md

Demonstrates how to initialize the SerpApi client, perform a search, access organic results, and paginate through results. Ensure your SERPAPI_KEY environment variable is set.

```python
import os
import serpapi

# Create a client with your API key
client = serpapi.Client(api_key=os.getenv("SERPAPI_KEY"))

# Perform a search
results = client.search(q="coffee", engine="google")

# Access results as a dictionary
for result in results.get("organic_results", []):
    print(f"{result['title']}: {result['link']}")

# Pagination
for page in results.yield_pages(max_pages=3):
    print(f"Page {len(page)}")
```

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

### GET Request for Locations

Source: https://github.com/serpapi/serpapi-python/blob/master/_autodocs/endpoints.md

This shows the direct HTTP GET request to retrieve locations. It's useful for understanding the API's base structure.

```http
GET https://serpapi.com/locations.json
```

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

### Initialize SerpApi Client

Source: https://github.com/serpapi/serpapi-python/blob/master/_autodocs/api-reference/client.md

Create a client instance using your API key. You can load the API key from an environment variable or pass it directly. A default timeout can also be specified.

```python
import os
import serpapi

# Create a client with an API key from environment
client = serpapi.Client(api_key=os.getenv("SERPAPI_KEY"))

# Create a client with a default timeout of 10 seconds
client = serpapi.Client(api_key=os.getenv("SERPAPI_KEY"), timeout=10)
```

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

### Basic Client Configuration

Source: https://github.com/serpapi/serpapi-python/blob/master/_autodocs/configuration.md

Initialize the SerpApi client with your API key. This is the minimum required configuration for making requests.

```python
import serpapi

# Minimal configuration with API key only
client = serpapi.Client(api_key="your_api_key")
```

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

### Standard SerpApi Client Usage

Source: https://github.com/serpapi/serpapi-python/blob/master/_autodocs/modules-and-imports.md

Import the serpapi library and initialize a client for making search requests. This is the most common way to use the library.

```python
import serpapi

client = serpapi.Client(api_key="...")
results = client.search(q="coffee")
```

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

### Get SERPAPI_KEY in Python

Source: https://github.com/serpapi/serpapi-python/blob/master/_autodocs/quick-reference.md

Retrieve the SERPAPI_KEY from environment variables in Python for use with the SerpApi client.

```python
import os
api_key = os.getenv("SERPAPI_KEY")
```

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

### Client Initialization

Source: https://github.com/serpapi/serpapi-python/blob/master/_autodocs/api-reference/client.md

Instantiate the SerpApi client with your API key. You can optionally set a default timeout for requests.

```APIDOC
## class `Client`

The main API client for SerpApi. Handles authentication and dispatches all search requests to the SerpApi service.

### Constructor

```python
def __init__(self, *, api_key=None, timeout=None)
```

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `api_key` | `str` | `None` | The API key for authenticating with SerpApi.com. Can be obtained from https://serpapi.com/manage-api-key. |
| `timeout` | `int | float` | `None` | Default timeout in seconds for all requests made by this client instance. Can be overridden per-request. |

**Example:**

```python
import os
import serpapi

# Create a client with an API key from environment
client = serpapi.Client(api_key=os.getenv("SERPAPI_KEY"))

# Create a client with a default timeout of 10 seconds
client = serpapi.Client(api_key=os.getenv("SERPAPI_KEY"), timeout=10)
```
```

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

### Get Next Page of Results

Source: https://github.com/serpapi/serpapi-python/blob/master/docs/index.md

Retrieve the next page of search results using the next_page() method.

```python
type(s.next_page())
```

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

### GET /searches/{search_id} API Endpoint

Source: https://github.com/serpapi/serpapi-python/blob/master/_autodocs/endpoints.md

This is the HTTP method and path for retrieving a search from the archive using its ID.

```http
GET https://serpapi.com/searches/{search_id}
```

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

### Initialize SerpApi Client

Source: https://github.com/serpapi/serpapi-python/blob/master/docs/index.md

Create a client instance to manage API requests, benefiting from connection pooling and automatic API key handling.

```python
client = serpapi.Client(api_key="secret_api_key")
s = client.search(q="Coffee", engine="google", location="Austin, Texas", hl="en", gl="us")
```

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

### Using SerpApi Module-Level Functions

Source: https://github.com/serpapi/serpapi-python/blob/master/_autodocs/api-reference/client.md

Demonstrates how to use the module-level functions for making API calls. Ensure you provide your API key.

```python
import serpapi

# Using module-level functions
results = serpapi.search(q="coffee", api_key="your_api_key")
account_info = serpapi.account(api_key="your_api_key")
```

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

### SerpApi JSON Pretty Printer

Source: https://github.com/serpapi/serpapi-python/blob/master/_autodocs/modules-and-imports.md

Provides a function to pretty-print JSON data, with optional syntax highlighting if Pygments is installed.

```python
import json
try:
    import pygments
    from pygments import highlight
    from pygments.lexers import JsonLexer
    from pygments.formatters import TerminalFormatter
except ImportError:
    pygments = None

def prettify_json(json_data):
    if pygments:
        return highlight(json_data, JsonLexer(), TerminalFormatter())
    else:
        return json_data
```

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

### Initialize HTTPClient

Source: https://github.com/serpapi/serpapi-python/blob/master/_autodocs/api-reference/http-client.md

Create an instance of the low-level HTTP client. Set the API key for authentication and an optional default timeout for requests.

```python
from serpapi.http import HTTPClient

# Create a low-level HTTP client
http_client = HTTPClient(api_key="your_api_key", timeout=10)
```

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

### Get Locations

Source: https://github.com/serpapi/serpapi-python/blob/master/_autodocs/endpoints.md

Retrieves a list of supported locations for localized searches. This can be done via the HTTP API or the Python client library.

```APIDOC
## GET /locations.json

### Description
Retrieves a list of supported locations for localized searches.

### Method
GET

### Endpoint
https://serpapi.com/locations.json

### Parameters
#### Query Parameters
- **api_key** (string) - Required - API authentication key.
- **q** (string) - Optional - Filter locations by name substring.
- **limit** (integer) - Optional - Maximum number of locations to return.

### Response
#### Success Response (200 OK)
- **id** (number) - Unique identifier for the location.
- **name** (string) - The name of the location.
- **canonical_name** (string) - The canonical name of the location.
- **country_code** (string) - The country code for the location.
- **gps** (array of numbers) - GPS coordinates [latitude, longitude].
- **keys** (array of strings) - Searchable keys for the location.

### Response Example
```json
[
  {
    "id": 1234,
    "name": "New York",
    "canonical_name": "New York, NY, USA",
    "country_code": "us",
    "gps": [40.7128, -74.0060],
    "keys": ["new york city"]
  }
]
```

### Error Responses
- **401**: Invalid or missing API key.
- **429**: Rate limit exceeded.
- **500**: Server error.
```

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

### Configuring Proxy for SerpApi Requests

Source: https://github.com/serpapi/serpapi-python/blob/master/_autodocs/configuration.md

Demonstrates how to route SerpApi requests through a proxy server by providing a dictionary of proxy URLs to the client. Ensure the proxy format is correct for your environment.

```python
import serpapi

client = serpapi.Client(api_key="your_api_key")

proxies = {
    "https": "https://username:password@proxy.example.com:8080",
}

results = client.search(q="coffee", proxies=proxies)
```

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

### Create SerpApi Client

Source: https://github.com/serpapi/serpapi-python/blob/master/_autodocs/quick-reference.md

Initialize the SerpApi client. You can provide your API key directly, use an environment variable, or create an unauthenticated client for module-level functions that require the API key per call.

```python
import os
import serpapi

# Basic client
client = serpapi.Client(api_key="your_api_key")

# Client with timeout
client = serpapi.Client(api_key=os.getenv("SERPAPI_KEY"), timeout=10)

# Unauthenticated (for module-level functions)
client = serpapi.Client()  # Must provide api_key to each call
```

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

### Paginate Through Search Results

Source: https://github.com/serpapi/serpapi-python/blob/master/_autodocs/00-START-HERE.md

Iterate over multiple pages of search results using `yield_pages` and process each result, for example, by printing the title.

```python
# Iterate multiple pages
for page in results.yield_pages(max_pages=5):
    for result in page["organic_results"]:
        print(result["title"])
```

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

### Pagination Loop

Source: https://github.com/serpapi/serpapi-python/blob/master/_autodocs/quick-reference.md

Iterate through paginated search results using the `yield_pages()` method. This example prints the title of each organic result on every page.

```python
page_count = 0
for page in results.yield_pages():
    page_count += 1
    for result in page.get("organic_results", []):
        print(f"Page {page_count}: {result['title']}")
```

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

### serpapi.Client().search()

Source: https://github.com/serpapi/serpapi-python/blob/master/docs/index.md

Initializes an API client and performs a search. The client manages the API key and connection pooling for repeated requests.

```APIDOC
## serpapi.Client().search()

### Description
Initializes an API client and performs a search. The client manages the API key and connection pooling for repeated requests.

### Method
POST

### Endpoint
https://serpapi.com/search.json

### Parameters
#### Path Parameters
- **api_key** (string) - Required - Your SerpApi API key. This is set during client initialization.

#### Query Parameters
- **q** (string) - Required - The search query.
- **engine** (string) - Required - The search engine to use (e.g., "google").
- **location** (string) - Optional - The location for the search.
- **hl** (string) - Optional - The host language for the search.
- **gl** (string) - Optional - The host geographic location for the search.

### Request Example
```python
import serpapi

client = serpapi.Client(api_key="secret_api_key")
s = client.search(
    q="Coffee",
    engine="google",
    location="Austin, Texas",
    hl="en",
    gl="us"
)
```

### Response
#### Success Response (200)
- **organic_results** (list) - A list of organic search results.
- **search_metadata** (dict) - Metadata about the search request.

#### Response Example
```json
{
  "organic_results": [
    {
      "position": 1,
      "title": "Coffee - Wikipedia",
      "link": "https://en.wikipedia.org/wiki/Coffee",
      "displayed_link": "en.wikipedia.org",
      "snippet": "Coffee is a brewed drink prepared from roasted coffee beans, the seeds of berries from certain Coffea species.",
      "thumbnail": "..."
    }
  ],
  "search_metadata": {
    "id": "64c148d35119a60ab1e00cc9",
    "status": "Success",
    "json_endpoint": "https://serpapi.com/searches/a15e1b92727f292c/64c148d35119a60ab1e00cc9.json",
    "created_at": "2023-07-26 16:24:51 UTC",
    "processed_at": "2023-07-26 16:24:51 UTC",
    "google_url": "https://www.google.com/search?q=Coffee&oq=Coffee&uule=w+CAIQICIdQXVzdGluLFRYLFRleGFzLFVuaXRlZCBTdGF0ZXM&hl=en&gl=us&sourceid=chrome&ie=UTF-8",
    "raw_html_file": "https://serpapi.com/searches/a15e1b92727f292c/64c148d35119a60ab1e00cc9.html",
    "total_time_taken": 1.55
  }
}
```
```

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

### Perform a search with advanced parameters

Source: https://github.com/serpapi/serpapi-python/blob/master/_autodocs/endpoints.md

Customize search results by providing additional parameters like `location`, `start`, and `num` to the `client.search` method.

```python
results = client.search(
    q="coffee",
    location="Austin, Texas",
    start=10,
    num=10
)
```

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

### Perform a basic search using SerpApi Python

Source: https://github.com/serpapi/serpapi-python/blob/master/_autodocs/endpoints.md

Use the `client.search` method to perform a search. Requires an API key and a query. The default engine is Google.

```python
import serpapi

client = serpapi.Client(api_key="your_api_key")

# Basic search
response = client.search(q="coffee", engine="google")
# Returns SerpResults object
```

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

### Search Google Autocomplete with SerpApi Python

Source: https://github.com/serpapi/serpapi-python/blob/master/README.md

Use this snippet to get Google autocomplete suggestions. Ensure your API key is set as an environment variable.

```python
import os
import serpapi

client = serpapi.Client(api_key=os.getenv("API_KEY"))
results = client.search({
    'engine': 'google_autocomplete',
    'q': 'coffee',
})
```

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

### Advanced Options: Proxy Configuration

Source: https://github.com/serpapi/serpapi-python/blob/master/_autodocs/quick-reference.md

Demonstrates how to configure proxy settings for your search requests.

```APIDOC
## Advanced Options: Proxy Configuration

### Description
Configure proxy settings for search requests.

### Method
`client.search()`

### Parameters
#### Request Body
- **proxies** (dict) - Required - A dictionary specifying proxy settings, e.g., `{"https": "https://proxy.example.com:8080"}`.
```

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

### Get Account Information

Source: https://github.com/serpapi/serpapi-python/blob/master/_autodocs/endpoints.md

Retrieves account information and usage statistics using the SerpApi API. This can be done directly via HTTP or through the Python client library.

```APIDOC
## GET /account.json

### Description
Retrieves account information and usage statistics.

### Method
GET

### Endpoint
https://serpapi.com/account.json

### Parameters
#### Query Parameters
- `api_key` (string) - Required - API authentication key.

### Response
#### Success Response (200 OK)
- `account_id` (string) - The unique identifier for the account.
- `api_key` (string) - The API key associated with the account.
- `plan_name` (string) - The name of the current subscription plan.
- `plan_credits` (number) - The number of credits available on the current plan.
- `plan_extended_credits` (number) - The number of extended credits available.
- `monthly_searches_limit` (number) - The maximum number of searches allowed per month.
- `monthly_searches_used` (number) - The number of searches used in the current month.
- `total_searches_used` (number) - The total number of searches used historically.

### Response Example
```json
{
  "account_id": "string",
  "api_key": "string",
  "plan_name": "string",
  "plan_credits": 1000,
  "plan_extended_credits": 0,
  "monthly_searches_limit": 10000,
  "monthly_searches_used": 500,
  "total_searches_used": 15000
}
```

### Error Responses
- `401` - Missing or invalid API key (Authentication error).
- `403` - Account suspended or disabled (Account status error).
- `429` - Rate limit exceeded (Rate limit error).
- `500` - Server error (Server-side error).
```

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

### Configure Client and Request Timeouts

Source: https://github.com/serpapi/serpapi-python/blob/master/_autodocs/README.md

Set a default timeout for the client or override it for individual requests. Also shows how to use proxies for requests.

```python
# Client-level timeout
client = serpapi.Client(api_key="...", timeout=10)

# Per-request timeout override
results = client.search(q="coffee", timeout=20)

# With proxy
results = client.search(
    q="coffee",
    proxies={"https": "https://proxy.example.com:8080"}
)
```

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

### Search Different Engines

Source: https://github.com/serpapi/serpapi-python/blob/master/_autodocs/README.md

Demonstrates how to perform searches on various search engines like Google, Bing, YouTube, and eBay using the 'engine' parameter.

```python
# Google (default)
google_results = client.search(q="coffee")

# Bing
bing_results = client.search(q="coffee", engine="bing")

# YouTube
youtube_results = client.search(search_query="coffee", engine="youtube")

# eBay
ebay_results = client.search(_nkw="coffee", engine="ebay")
```

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

### Basic Google Search

Source: https://github.com/serpapi/serpapi-python/blob/master/_autodocs/configuration.md

Perform a basic Google search using the SerpApi client. Ensure you have initialized the client with your API key.

```python
import serpapi

client = serpapi.Client(api_key="your_api_key")

# Basic search
results = client.search(q="coffee")
```

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

### Get HTML output from SerpApi search

Source: https://github.com/serpapi/serpapi-python/blob/master/_autodocs/endpoints.md

To retrieve raw HTML instead of JSON, set the `output` parameter to `html`. This returns a string containing the HTML document.

```python
html = client.search(q="coffee", engine="google", output="html")
# Returns str
```

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

### Retry with Backoff on Timeout

Source: https://github.com/serpapi/serpapi-python/blob/master/_autodocs/quick-reference.md

Implement a retry mechanism with exponential backoff for `TimeoutError` to handle transient network issues or slow responses. This example retries up to 3 times.

```python
import time

for attempt in range(3):
    try:
        results = client.search(q="coffee")
        break
    except serpapi.TimeoutError:
        if attempt < 2:
            time.sleep(2 ** attempt)
        else:
            raise
```

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

### Perform Google Search with Parameters

Source: https://github.com/serpapi/serpapi-python/blob/master/_autodocs/quick-reference.md

Execute a Google search using the client, specifying common parameters like query, location, language, and pagination.

```python
results = client.search(
    q="coffee",                              # Query
    engine="google",                         # Engine (default)
    location="Austin, Texas, United States", # Location
    gl="us",                                 # Country (ISO 3166-1 alpha-2)
    hl="en",                                 # Language (ISO 639-1)
    num=10,                                  # Results per page
    start=0,                                 # Pagination offset
    output="json"                            # Output format
)
```

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

### Importing Core Classes from SerpApi

Source: https://github.com/serpapi/serpapi-python/blob/master/_autodocs/modules-and-imports.md

Import the main API client and response wrapper classes from the serpapi package.

```python
from serpapi import Client, SerpResults
```

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

### Google Search Response Structure

Source: https://github.com/serpapi/serpapi-python/blob/master/_autodocs/quick-reference.md

Example of the JSON structure returned by a Google search via SerpApi. This includes metadata, search parameters, and various result sections.

```json
{
    "search_metadata": {
        "id": "search_id",
        "status": "Success",
        "json_endpoint": "url",
        "created_at": "timestamp",
        "processed_at": "timestamp",
        "google_url": "url",
        "raw_html_file": "url",
        "total_time_taken": 0.5
    },
    "search_parameters": {
        "q": "coffee",
        "engine": "google",
        "location": "..."
    },
    "organic_results": [
        {
            "position": 1,
            "title": "Result Title",
            "link": "https://example.com",
            "displayed_link": "example.com",
            "snippet": "Description...",
            "rating": 4.5,
            "review_count": 100
        },
        # ... more results
    ],
    "knowledge_graph": {...},      # If available
    "answer_box": {...},           # If available
    "related_searches": [...],
    "people_also_search_for": [...],
    "serpapi_pagination": {
        "next": "next_page_url"
    }
}
```

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

### Get Raw HTML Response

Source: https://github.com/serpapi/serpapi-python/blob/master/_autodocs/types.md

Use this snippet when you need to retrieve raw HTML content from a search query. The response is a plain string and requires direct string handling.

```python
import serpapi

client = serpapi.Client(api_key="your_api_key")
html = client.search(q="coffee", output="html")

# Process HTML string
if "coffee" in html:
    print("Query term found in HTML response")
```

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

### Retrieve Account Information with Python Client

Source: https://github.com/serpapi/serpapi-python/blob/master/_autodocs/endpoints.md

Use this snippet to fetch your SerpApi account details, including plan information and search usage. Ensure you have initialized the client with your API key.

```python
import serpapi

client = serpapi.Client(api_key="your_api_key")

account = client.account()

print(f"Plan: {account['plan_name']}")
print(f"Searches used: {account['monthly_searches_used']}/{account['monthly_searches_limit']}")
print(f"Total searches: {account['total_searches_used']}")
```

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

### Use Proxy with SerpApi Search

Source: https://github.com/serpapi/serpapi-python/blob/master/_autodocs/quick-reference.md

Configure a proxy server for your search requests. Ensure the proxy is correctly formatted.

```python
results = client.search(
    q="coffee",
    proxies={"https": "https://proxy.example.com:8080"}
)
```

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

### SerpApi with Type Hints

Source: https://github.com/serpapi/serpapi-python/blob/master/_autodocs/modules-and-imports.md

Utilize type hints for better code readability and maintainability when working with the SerpApi client and search results, especially for pagination.

```python
from typing import Optional
from serpapi import Client, SerpResults

def search_and_paginate(
    client: Client,
    query: str,
    max_pages: int = 5
) -> list[SerpResults]:
    results = client.search(q=query)
    pages = []
    for page in results.yield_pages(max_pages=max_pages):
        pages.append(page)
    return pages
```

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

### Search Parameters Dictionary

Source: https://github.com/serpapi/serpapi-python/blob/master/_autodocs/types.md

Define search parameters as a dictionary for the SerpApi API. Common keys include 'q' for query, 'engine', 'location', 'gl', 'hl', 'start', 'num', and 'output'.

```python
params = {
    "q": "coffee",
    "engine": "google",
    "location": "Austin, Texas",
    "num": 10
}
```

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

### Client Configuration with Timeout

Source: https://github.com/serpapi/serpapi-python/blob/master/_autodocs/configuration.md

Configure the SerpApi client with a default timeout. This timeout can be overridden for individual requests.

```python
import serpapi

# Set a 10-second timeout for all requests
client = serpapi.Client(
    api_key="your_api_key",
    timeout=10
)

# Make a request with the default timeout
results = client.search(q="coffee")

# Override timeout for a specific request
results = client.search(q="coffee", timeout=20)
```

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

### Pagination with SerpApi Python

Source: https://github.com/serpapi/serpapi-python/blob/master/_autodocs/README.md

Demonstrates how to retrieve the next page of search results or iterate through multiple pages using the SerpResults object. Ensure you have a valid SerpResults object from a previous search.

```python
# Get the next page
next_page = results.next_page()

# Iterate through multiple pages
for page in results.yield_pages(max_pages=10):
    process(page)
```

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

### Retrieve Account Information

Source: https://github.com/serpapi/serpapi-python/blob/master/_autodocs/api-reference/client.md

Use the `account` method to get details about your SerpApi account, including usage statistics like searches used and plan information. This method does not require any specific parameters.

```python
client = serpapi.Client(api_key="your_api_key")

# Get account information
account_info = client.account()
print(f"Searches used: {account_info['total_searches_used']}")
print(f"Plan: {account_info['plan_name']}")
```

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

### Get Supported Locations

Source: https://github.com/serpapi/serpapi-python/blob/master/_autodocs/api-reference/client.md

The `locations` method retrieves a list of supported Google search locations. You can optionally filter these locations by name using the `q` parameter or limit the number of results with the `limit` parameter.

```python
client = serpapi.Client(api_key="your_api_key")

# Get all locations
locations = client.locations()

# Filter locations by name
locations = client.locations(q="Austin")

# Limit the number of results
locations = client.locations(q="Austin", limit=5)
```

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

### Simple Search with Error Handling

Source: https://github.com/serpapi/serpapi-python/blob/master/_autodocs/README.md

Perform a basic search and handle potential HTTP errors. Ensure the SERPAPI_KEY environment variable is set.

```python
import os
import serpapi

client = serpapi.Client(api_key=os.getenv("SERPAPI_KEY"))

try:
    results = client.search(q="coffee", location="Austin, Texas")
    for result in results.get("organic_results", []):
        print(result["title"])
except serpapi.HTTPError as e:
    print(f"Error: {e.status_code} - {e.error}")
```

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

### Handling HTTPError with Status Codes

Source: https://github.com/serpapi/serpapi-python/blob/master/_autodocs/errors.md

This example demonstrates how to catch `HTTPError` and inspect its attributes like `status_code` and `error` to provide specific user feedback. It's useful for diagnosing API communication issues.

```python
import serpapi

client = serpapi.Client(api_key="your_api_key")

try:
    results = client.search({"q": ""})  # Empty query
except serpapi.HTTPError as e:
    print(f"HTTP Status: {e.status_code}")
    print(f"Error Message: {e.error}")
    
    if e.status_code == 401:
        print("Your API key is invalid. Please check it.")
    elif e.status_code == 400:
        print(f"Invalid request: {e.error}")
    elif e.status_code == 429:
        print("You've exceeded your rate limit. Wait before retrying.")
```

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

### Basic Google Search with SerpApi

Source: https://github.com/serpapi/serpapi-python/blob/master/README.md

Perform a basic Google search for 'coffee' using the SerpApi Python client. Ensure your SERPAPI_KEY is set as an environment variable.

```python
import os
import serpapi

client = serpapi.Client(api_key=os.getenv("SERPAPI_KEY"))
results = client.search({
  "engine": "google",
  "q": "coffee"
})

print(results)
```

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

### SSL/Certificate Management for Corporate Environments

Source: https://github.com/serpapi/serpapi-python/blob/master/_autodocs/configuration.md

Shows how to manage SSL/certificate verification for corporate environments with custom Certificate Authorities (CAs) or when using client certificates for mutual TLS. Specify the CA bundle path or client certificate and key paths.

```python
import serpapi

client = serpapi.Client(api_key="your_api_key")

# Use custom CA bundle
results = client.search(
    q="coffee",
    verify="/etc/ssl/certs/ca-bundle.crt"
)

# Use client certificate for mutual TLS
results = client.search(
    q="coffee",
    cert=("/path/to/client.crt", "/path/to/client.key")
)
```

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

### SerpResults Constructor

Source: https://github.com/serpapi/serpapi-python/blob/master/_autodocs/api-reference/serpresults.md

Initializes a SerpResults object with search data and a client instance for pagination.

```APIDOC
## SerpResults Constructor

### Description
Initializes a `SerpResults` object with the JSON response data from a SerpApi search and a `Client` instance for executing pagination requests.

### Method
```python
def __init__(self, data, *, client)
```

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **data** (`dict`) - Required - The JSON response data from the SerpApi search endpoint.
- **client** (`Client`) - Required - The `Client` instance that executed the request. Used for pagination requests.

### Request Example
```python
# This constructor is typically called internally by the Client.search() method.
# Example of how the results object is used after a search:
import serpapi

client = serpapi.Client(api_key="your_api_key")
results = client.search(q="coffee")

# Access data as a dictionary
print(results["search_metadata"]["id"])
print(results.get("organic_results", []))
```

### Response
None (This is a constructor)

### Error Handling
None
```

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

### Project File Structure

Source: https://github.com/serpapi/serpapi-python/blob/master/_autodocs/README.md

Overview of the directory structure for the serpapi-python project, detailing the purpose of each markdown file.

```text
output/
├── README.md                    (this file)
├── configuration.md             (setup, options, env vars)
├── types.md                     (data structures, type info)
├── endpoints.md                 (HTTP API details)
├── errors.md                    (exception handling)
└── api-reference/
    ├── client.md               (Client class reference)
    ├── serpresults.md          (SerpResults class reference)
    └── http-client.md          (HTTPClient class reference)
```

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

### Search Home Depot with SerpApi Python

Source: https://github.com/serpapi/serpapi-python/blob/master/README.md

Use this snippet to search on Home Depot. Ensure your API key is set as an environment variable.

```python
import os
import serpapi

client = serpapi.Client(api_key=os.getenv("API_KEY"))
results = client.search({
    'engine': 'home_depot',
    'q': 'table',
})
```

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

### Tag and Push for Release

Source: https://github.com/serpapi/serpapi-python/blob/master/README.md

Tag the current commit and push the tag to trigger the automated release pipeline. Ensure you have the necessary permissions and secrets configured.

```bash
git tag v1.2.3
git push origin v1.2.3
```

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

### Search Google with SerpApi Python

Source: https://github.com/serpapi/serpapi-python/blob/master/README.md

Use this snippet to search on Google. Ensure your API key is set as an environment variable.

```python
import os
import serpapi

client = serpapi.Client(api_key=os.getenv("API_KEY"))
results = client.search({
    'engine': 'google',
    'q': 'coffee'
})
```

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

### client.search(q, output='html')

Source: https://github.com/serpapi/serpapi-python/blob/master/_autodocs/types.md

Performs a search query and returns raw HTML content when output is set to 'html'. The response is a string and is HTML-encoded.

```APIDOC
## client.search(q, output='html')

### Description
Performs a search query and returns raw HTML content when output is set to 'html'. The response is a string and is HTML-encoded.

### Method
POST

### Endpoint
/

### Parameters
#### Query Parameters
- **q** (str) - Required - The search query.
- **output** (str) - Optional - Specifies the output format. Use 'html' for raw HTML.

### Request Example
```python
import serpapi

client = serpapi.Client(api_key="your_api_key")
html = client.search(q="coffee", output="html")

# Process HTML string
if "coffee" in html:
    print("Query term found in HTML response")
```

### Response
#### Success Response (200)
**Type:** `str`

**Notes:**
- Content is HTML-encoded.
- Not wrapped in `SerpResults`.
- Access via direct string handling.
```

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

### Handling Missing API Key with SerpApi Client

Source: https://github.com/serpapi/serpapi-python/blob/master/_autodocs/errors.md

Demonstrates how to catch an HTTPError when a client is used without an API key and an API method is called. This scenario typically results in a 401 Unauthorized status.

```python
import serpapi

# Creating a client without an API key
client = serpapi.Client()  # api_key is None

try:
    # Calling a method without providing api_key
    # This will raise HTTPError (401) rather than APIKeyNotProvided
    results = client.search(q="coffee")
except serpapi.HTTPError as e:
    if e.status_code == 401:
        print("API key is missing or invalid.")
```

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

### Run Test Suite

Source: https://github.com/serpapi/serpapi-python/blob/master/_autodocs/quick-reference.md

Execute the test suite using pytest. Authentication can be provided via an environment variable.

```bash
# Run test suite
pytest
```

```bash
# With API key
API_KEY=your_key pytest
```

```bash
# Specific test
pytest tests/test_integration.py
```

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

### Search YouTube with SerpApi Python

Source: https://github.com/serpapi/serpapi-python/blob/master/README.md

Use this snippet to search on YouTube. Ensure your API key is set as an environment variable.

```python
import os
import serpapi

client = serpapi.Client(api_key=os.getenv("API_KEY"))
results = client.search({
    'engine': 'youtube',
    'search_query': 'coffee',
})
```

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

### Basic Search with serpapi.search()

Source: https://github.com/serpapi/serpapi-python/blob/master/docs/index.md

Perform a search using the top-level search function. Pass API parameters directly.

```python
import serpapi
s = serpapi.search(q="Coffee", engine="google", location="Austin, Texas", hl="en", gl="us")
print(s["organic_results"][0]["link"])
```

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

### Search Google Immersive Product with SerpApi Python

Source: https://github.com/serpapi/serpapi-python/blob/master/README.md

Use this snippet to search for Google Immersive Products. Ensure your API key is set as an environment variable and provide the necessary page_token.

```python
import os
import serpapi

client = serpapi.Client(api_key=os.getenv("API_KEY"))
results = client.search({
    'engine': 'google_immersive_product',
    'page_token': 'eyJlaSI6Im5ZVmxaOXVVTDY2X3A4NFBqTnZELUFjIiwicHJvZHVjdGlkIjoiIiwiY2F0YWxvZ2lkIjoiNTE1NDU2NTc1NTc5MzcxMDY3NSIsImhlYWRsaW5lT2ZmZXJEb2NpZCI6IjI1MDkyMjcwMDUzMjk2NzQwODMiLCJpbWFnZURvY2lkIjoiMTYzOTg5MjU0MDcwMDU4MDA1NTQiLCJyZHMiOiJQQ18zNDg4MDE0MTg3ODgxNzc5NjU0fFBST0RfUENfMzQ4ODAxNDE4Nzg4MTc3OTY1NCIsInF1ZXJ5IjoibGcrdHYiLCJncGNpZCI6IjM0ODgwMTQxODc4ODE3Nzk2NTQiLCJtaWQiOiI1NzY0NjI3ODM3Nzc5MTUzMTMiLCJwdnQiOiJoZyIsInV1bGUiOm51bGx9=',
})
```

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

### Process Search Results with Type Hints

Source: https://github.com/serpapi/serpapi-python/blob/master/_autodocs/types.md

Use this function to execute a search with the SerpApi client and return typed results. Ensure the client is properly initialized.

```python
from typing import Dict, Any, Optional, List
from serpapi import Client, SerpResults

def process_search_results(
    client: Client,
    query: str,
    params: Optional[Dict[str, Any]] = None
) -> SerpResults:
    """Execute a search and return results."""
    if params is None:
        params = {}
    params["q"] = query
    return client.search(params)
```

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

### Set Environment Variable on Windows Command Prompt

Source: https://github.com/serpapi/serpapi-python/blob/master/_autodocs/configuration.md

Shows how to set the SERPAPI_KEY environment variable on Windows using the Command Prompt 'set' command.

```cmd
set SERPAPI_KEY=your_actual_api_key
python your_script.py
```

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

### SerpApi Core Client and Search Functions

Source: https://github.com/serpapi/serpapi-python/blob/master/_autodocs/modules-and-imports.md

Provides the main API client class and module-level functions for interacting with the SerpApi.

```python
from serpapi.models import SerpResults
from serpapi.exceptions import SearchIDNotProvided
from http import HTTPClient

class Client:
    def __init__(self, *, api_key=None, timeout=None):
        pass
    def search(self, params=None, **kwargs):
        pass
    def search_archive(self, params=None, **kwargs):
        pass
    def locations(self, params=None, **kwargs):
        pass
    def account(self, params=None, **kwargs):
        pass

def search(*args, **kwargs):
    pass
def search_archive(*args, **kwargs):
    pass
def locations(*args, **kwargs):
    pass
def account(*args, **kwargs):
    pass
```

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

### Performing a Search

Source: https://github.com/serpapi/serpapi-python/blob/master/_autodocs/api-reference/client.md

Use the `search` method to fetch results from SerpApi. You can pass parameters as a dictionary or as keyword arguments.

```APIDOC
### Method: `search`

Fetch search results from SerpApi for a given set of parameters.

```python
def search(self, params: dict = None, **kwargs) -> SerpResults | str
```

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `params` | `dict` | `None` | A dictionary of search parameters. When provided, the dictionary is used as the base parameters for the API request. |
| `q` | `str` | — | The search query (parameter name depends on the engine; for Google it is `q`). |
| `engine` | `str` | `"google"` | The search engine to use. Supported engines: `google`, `bing`, `baidu`, `yandex`, `yahoo`, `duckduckgo`, `ebay`, `walmart`, `naver`, `home_depot`, `apple_app_store`, `youtube`, `google_images`, `google_scholar`, `google_autocomplete`, `google_jobs`, `google_maps`, `google_play`, `google_events`, `google_local_services`, `google_reverse_image`, `google_immersive_product`. |
| `output` | `str` | `"json"` | The output format. Either `"json"` (returns `SerpResults`) or `"html"` (returns raw HTML string). |
| `api_key` | `str` | — | API key to override the client's default API key for this request. |
| `timeout` | `int | float` | — | Timeout in seconds to override the client's default timeout for this request. |
| `proxies` | `dict` | — | Dictionary of proxy URLs to use for the request. Passed to `requests` library. |
| `verify` | `bool | str` | — | Whether to verify SSL certificates. Passed to `requests` library. |
| `stream` | `bool` | — | Whether to stream the response. Passed to `requests` library. |
| `cert` | `str | tuple` | — | Client-side certificate path. Passed to `requests` library. |
| `**kwargs` | — | — | Any additional parameters are merged into `params` and sent to the API. |

**Return type:** 
- `SerpResults` if `output="json"` and the response is valid JSON.
- `str` if `output="html"` or the response is not JSON-parseable.

**Raises:**
- `HTTPError` — Status code is not 200, or the API returns an error.
- `HTTPConnectionError` — Network connectivity issue.
- `TimeoutError` — Request times out.

**Example:**

```python
import serpapi

client = serpapi.Client(api_key="your_api_key")

# Simple search with kwargs
results = client.search(q="coffee", engine="google")

# Search using a params dictionary
params = {
    "q": "coffee",
    "engine": "google",
    "location": "Austin, Texas"
}
results = client.search(params)

# Mixed: dictionary + kwargs
results = client.search(params, output="json")

# Get HTML output
html_response = client.search(q="coffee", output="html")

# With timeout override
results = client.search(q="coffee", timeout=20)
```
```

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

### Perform YouTube Search

Source: https://github.com/serpapi/serpapi-python/blob/master/_autodocs/quick-reference.md

Execute a YouTube search using the client. Note the use of `search_query` parameter instead of `q`.

```python
results = client.search(
    search_query="coffee",  # Note: different parameter name
    engine="youtube"
)
```