# SerpApi Python

> Official Python client for SerpApi search data in applications, AI workflows, RAG, and data pipelines.

## Homepage

Integrate search data into your AI workflow, RAG or fine-tuning pipeline, Python application, or data product using the official wrapper for [SerpApi](https://serpapi.com).

SerpApi supports Google, Google Maps, Google Shopping, Bing, DuckDuckGo, Baidu, Yandex, Yahoo, eBay, YouTube, App Stores, Walmart, Home Depot, Naver, and many more engines.

Query a wide range of data at scale, including web search results, local business listings, shopping results, flight schedules, stock market data, job listings, trends, news headlines, AI Overview results, and video search results.

### Install

### pip

```bash
pip install serpapi
```

### uv

```bash
uv add serpapi
```

Python 3.6 or newer is required by the package.

### First Request

Sign up at [SerpApi](https://serpapi.com/users/sign_up), copy your API key from the [dashboard](https://serpapi.com/manage-api-key), and set it in your shell:

### macOS / Linux

```bash
export SERPAPI_KEY="secret_api_key"
```

### Windows

```powershell
$env:SERPAPI_KEY = "secret_api_key"
```

```python
import os
import serpapi

client = serpapi.Client(api_key=os.environ["SERPAPI_KEY"])
results = client.search(
    engine="google",
    q="coffee",
    location="Austin, Texas",
    hl="en",
    gl="us",
)

print(results["organic_results"][0]["link"])
```

The `results` variable contains a `SerpResults` object. It behaves like a standard dictionary and adds convenience helpers for response conversion, pagination, and fetching search archives.

Request parameters map directly to the SerpApi HTTP API. For the full engine list and engine-specific parameters, use the [SerpApi API documentation](https://serpapi.com/search-api). Use the [SerpApi Playground](https://serpapi.com/playground) to build and test a request before moving it into Python.

### Documentation Map

Choose the path that matches what you are building. Start with setup and a first request, then move into client behavior, request parameters, pagination, error handling, or engine-specific examples.

- New integrations: read [Getting Started](https://serpapi.github.io/serpapi-python/user-guide/getting-started.html), then [Client Usage](https://serpapi.github.io/serpapi-python/user-guide/client-usage.html).
- Existing `google-search-results` users: follow the [Migration Guide](https://serpapi.github.io/serpapi-python/user-guide/migrating-from-google-search-results.html).
- Engine setup: use [Parameters and Engines](https://serpapi.github.io/serpapi-python/user-guide/parameters-and-engines.html) with the [SerpApi Playground](https://serpapi.com/playground).
- Production workflows: review [pagination](https://serpapi.github.io/serpapi-python/user-guide/pagination.html), [timeouts and errors](https://serpapi.github.io/serpapi-python/user-guide/errors-and-timeouts.html), [request options](https://serpapi.github.io/serpapi-python/user-guide/request-options.html), [account/location helpers](https://serpapi.github.io/serpapi-python/user-guide/account-and-locations.html), [async search archive](https://serpapi.github.io/serpapi-python/user-guide/async-search-archive.html), [JSON Restrictor](https://serpapi.github.io/serpapi-python/user-guide/json-restrictor.html), and [zero trace controls](https://serpapi.github.io/serpapi-python/user-guide/zero-trace.html).
- [Examples](https://serpapi.github.io/serpapi-python/docs/examples/index.html): browse focused recipes grouped by search engines, AI answers, local/maps, shopping, travel, finance, trends, jobs, events, media, apps, and research.

#### User Guide

- [Getting Started](https://serpapi.github.io/serpapi-python/user-guide/getting-started.html)
- [Client Usage](https://serpapi.github.io/serpapi-python/user-guide/client-usage.html)
- [Parameters and Engines](https://serpapi.github.io/serpapi-python/user-guide/parameters-and-engines.html)
- [Pagination](https://serpapi.github.io/serpapi-python/user-guide/pagination.html)
- [Errors and Timeouts](https://serpapi.github.io/serpapi-python/user-guide/errors-and-timeouts.html)
- [Account and Locations](https://serpapi.github.io/serpapi-python/user-guide/account-and-locations.html)

#### Migration

- [Migrating from google-search-results](https://serpapi.github.io/serpapi-python/user-guide/migrating-from-google-search-results.html)

#### Advanced Usage

- [Async Search Archive](https://serpapi.github.io/serpapi-python/user-guide/async-search-archive.html)
- [Parallel Requests with Threads](https://serpapi.github.io/serpapi-python/user-guide/threading.html)
- [Parallel Requests with Multiprocessing](https://serpapi.github.io/serpapi-python/user-guide/multiprocessing.html)
- [Zero Trace and Cache Controls](https://serpapi.github.io/serpapi-python/user-guide/zero-trace.html)
- [JSON Restrictor](https://serpapi.github.io/serpapi-python/user-guide/json-restrictor.html)
- [Request Options](https://serpapi.github.io/serpapi-python/user-guide/request-options.html)

#### Examples

- [Examples Overview](https://serpapi.github.io/serpapi-python/docs/examples/index.html)
- Search Engines: [Google](https://serpapi.github.io/serpapi-python/docs/examples/google-across-countries.html), [Bing](https://serpapi.github.io/serpapi-python/docs/examples/bing-search.html), [DuckDuckGo](https://serpapi.github.io/serpapi-python/docs/examples/duckduckgo-search.html), [Baidu](https://serpapi.github.io/serpapi-python/docs/examples/baidu-search.html)
- AI Answers: [Google AI Overview](https://serpapi.github.io/serpapi-python/docs/examples/google-ai-overview.html)
- Local and Maps: [Google Maps](https://serpapi.github.io/serpapi-python/docs/examples/google-maps-local-business.html), [Google Local Services](https://serpapi.github.io/serpapi-python/docs/examples/google-local-services.html)
- Shopping and Marketplaces: [Google Shopping](https://serpapi.github.io/serpapi-python/docs/examples/google-shopping-products.html), [Amazon](https://serpapi.github.io/serpapi-python/docs/examples/amazon-product-search.html), [Walmart](https://serpapi.github.io/serpapi-python/docs/examples/walmart-product-search.html), [eBay](https://serpapi.github.io/serpapi-python/docs/examples/ebay-product-listings.html), [Home Depot](https://serpapi.github.io/serpapi-python/docs/examples/home-depot-product-search.html)
- Travel and Hospitality: [Google Flights](https://serpapi.github.io/serpapi-python/docs/examples/google-flights-travel.html), [Tripadvisor](https://serpapi.github.io/serpapi-python/docs/examples/tripadvisor-travel-search.html)
- Finance, Trends, Jobs, and Events: [Google Finance](https://serpapi.github.io/serpapi-python/docs/examples/google-finance-market-data.html), [Google Trends](https://serpapi.github.io/serpapi-python/docs/examples/google-trends-demand.html), [Google Jobs](https://serpapi.github.io/serpapi-python/docs/examples/google-jobs-listings.html), [Google Events](https://serpapi.github.io/serpapi-python/docs/examples/google-events-discovery.html)
- Media, Apps, and Research: [YouTube](https://serpapi.github.io/serpapi-python/docs/examples/youtube-video-search.html), [Google Images](https://serpapi.github.io/serpapi-python/docs/examples/google-images-search.html), [Google Scholar](https://serpapi.github.io/serpapi-python/docs/examples/google-scholar-research.html), [Google Play](https://serpapi.github.io/serpapi-python/docs/examples/google-play-store-apps.html)

## Getting Started

SerpApi Python is the official Python client for [SerpApi](https://serpapi.com). It wraps SerpApi HTTP endpoints with a small Python API while keeping request parameters close to the underlying API.

Use this page to install the package, configure your API key, and make a first Google Search request.

### Installation

### pip

```bash
pip install serpapi
```

### uv project

```bash
uv add serpapi
```

### uv environment

```bash
uv pip install serpapi
```

Python 3.6 or newer is required by the package.

Create or sign in to your SerpApi account, copy your API key from the [dashboard](https://serpapi.com/manage-api-key), and set it in the environment:

### macOS / Linux

```bash
export SERPAPI_KEY="secret_api_key"
```

### Windows

```powershell
$env:SERPAPI_KEY = "secret_api_key"
```

### First Search

```python
import os
import serpapi

client = serpapi.Client(api_key=os.environ["SERPAPI_KEY"], timeout=20)

results = client.search(
    engine="google",
    q="coffee shops",
    location="Austin, Texas",
    hl="en",
    gl="us",
)

first_result = results["organic_results"][0]
print(first_result["title"])
print(first_result["link"])
```

`client.search()` returns a `SerpResults` object for JSON responses. It behaves like a dictionary and adds helpers such as `as_dict()`, `next_page()`, and `yield_pages()`.

### What the Parameters Mean

The example above sends a Google Search request:

| Parameter | Purpose |
| --- | --- |
| `engine` | Selects the SerpApi engine. `google` is Google Search. |
| `q` | Search query. |
| `location` | Search location used by SerpApi. |
| `hl` | Interface language. |
| `gl` | Country for Google results. |

SerpApi supports many engines and engine-specific parameters. The authoritative list lives in the [SerpApi API documentation](https://serpapi.com/search-api). The [SerpApi Playground](https://serpapi.com/playground) is the fastest way to build and test a request before moving it into Python.

### When to Use the Client

Use `serpapi.Client` for application code, scripts that make more than one request, pagination, and concurrent workloads. The client stores the API key, timeout, and HTTP session configuration in one place.

The module-level helpers are useful for quick experiments:

```python
import serpapi

results = serpapi.search(
    api_key="secret_api_key",
    engine="google",
    q="coffee",
)
```

For production code, prefer a client instance:

```python
client = serpapi.Client(api_key="secret_api_key", timeout=20)
results = client.search(engine="google", q="coffee")
```

### Next Steps

- Read [Client Usage](https://serpapi.github.io/serpapi-python/user-guide/client-usage.html) for response helpers, request options, and archive helpers.
- Read [Pagination](https://serpapi.github.io/serpapi-python/user-guide/pagination.html) when collecting more than one page of results.
- Try [Google Across Countries](https://serpapi.github.io/serpapi-python/docs/examples/google-across-countries.html) for a practical localization example.

## API Reference

### Search Client
> Main entry points for making requests and working with responses.

- [Client](https://serpapi-python.readthedocs.io/en/latest/reference/Client.html): A class that handles API requests to SerpApi in a user-friendly manner
- [SerpResults](https://serpapi-python.readthedocs.io/en/latest/reference/SerpResults.html): A dictionary-like object that represents the results of a SerpApi request

### Exceptions
> Errors raised by the client for API, HTTP, connection, and timeout failures.

- [SerpApiError](https://serpapi-python.readthedocs.io/en/latest/reference/SerpApiError.html): Base class for exceptions in this module
- [APIKeyNotProvided](https://serpapi-python.readthedocs.io/en/latest/reference/APIKeyNotProvided.html): API key is not provided
- [SearchIDNotProvided](https://serpapi-python.readthedocs.io/en/latest/reference/SearchIDNotProvided.html): Search ID is not provided
- [HTTPError](https://serpapi-python.readthedocs.io/en/latest/reference/HTTPError.html): HTTP Error
- [HTTPConnectionError](https://serpapi-python.readthedocs.io/en/latest/reference/HTTPConnectionError.html): Connection Error
- [TimeoutError](https://serpapi-python.readthedocs.io/en/latest/reference/TimeoutError.html): Timeout Error

## More LLM Context

- [Full LLM documentation](https://serpapi.github.io/serpapi-python/llms-full.txt)
- [Documentation homepage](https://serpapi.github.io/serpapi-python/index.html)