+
+:::
+
+:::{.docs-home-nav__sidebar}
+
+### User Guide
+
+- [Getting Started](user-guide/getting-started.md)
+- [Client Usage](user-guide/client-usage.md)
+- [Parameters and Engines](user-guide/parameters-and-engines.md)
+- [Pagination](user-guide/pagination.md)
+- [Errors and Timeouts](user-guide/errors-and-timeouts.md)
+- [Account and Locations](user-guide/account-and-locations.md)
+
+### Migration
+
+- [Migrating from google-search-results](user-guide/migrating-from-google-search-results.md)
+
+### Advanced Usage
+
+- [Async Search Archive](user-guide/async-search-archive.md)
+- [Parallel Requests with Threads](user-guide/threading.md)
+- [Parallel Requests with Multiprocessing](user-guide/multiprocessing.md)
+- [Zero Trace and Cache Controls](user-guide/zero-trace.md)
+- [JSON Restrictor](user-guide/json-restrictor.md)
+- [Request Options](user-guide/request-options.md)
+
+### Examples
+
+- [Examples Overview](docs/examples/index.qmd)
+- Search Engines: [Google](docs/examples/google-across-countries.md), [Bing](docs/examples/bing-search.md), [DuckDuckGo](docs/examples/duckduckgo-search.md), [Baidu](docs/examples/baidu-search.md)
+- AI Answers: [Google AI Overview](docs/examples/google-ai-overview.md)
+- Local and Maps: [Google Maps](docs/examples/google-maps-local-business.md), [Google Local Services](docs/examples/google-local-services.md)
+- Shopping and Marketplaces: [Google Shopping](docs/examples/google-shopping-products.md), [Amazon](docs/examples/amazon-product-search.md), [Walmart](docs/examples/walmart-product-search.md), [eBay](docs/examples/ebay-product-listings.md), [Home Depot](docs/examples/home-depot-product-search.md)
+- Travel and Hospitality: [Google Flights](docs/examples/google-flights-travel.md), [Tripadvisor](docs/examples/tripadvisor-travel-search.md)
+- Finance, Trends, Jobs, and Events: [Google Finance](docs/examples/google-finance-market-data.md), [Google Trends](docs/examples/google-trends-demand.md), [Google Jobs](docs/examples/google-jobs-listings.md), [Google Events](docs/examples/google-events-discovery.md)
+- Media, Apps, and Research: [YouTube](docs/examples/youtube-video-search.md), [Google Images](docs/examples/google-images-search.md), [Google Scholar](docs/examples/google-scholar-research.md), [Google Play](docs/examples/google-play-store-apps.md)
+
+:::
+
+:::
diff --git a/docs/index.rst b/docs/index.rst
deleted file mode 100644
index 717c69a..0000000
--- a/docs/index.rst
+++ /dev/null
@@ -1,191 +0,0 @@
-.. serpapi-python documentation master file, created by
- sphinx-quickstart on Sun Apr 3 21:09:40 2022.
- You can adapt this file completely to your liking, but it should at least
- contain the root `toctree` directive.
-
-**serpapi-python**
-==================
-
-an official Python client library for `SerpApi `_.
-
---------------
-
-Installation
-------------
-
-To install ``serpapi-python``, simply use `pip`::
-
- $ pip install serpapi
-
-
-Please note that Python 3.6+ is required.
-
-
-Usage
------
-
-Usage of this module is fairly straight-forward. In general, this module attempts to be as close to the actual API as possible, while still being Pythonic.
-
-For example, the API endpoint ``https://serpapi.com/search.json`` is represented by the method ``serpapi.search()``.
-
-.. code-block:: python
-
- >>> import serpapi
- >>> s = serpapi.search(q="Coffee", engine="google", location="Austin, Texas", hl="en", gl="us")
- >>> s["organic_results"][0]["link"]
- 'https://en.wikipedia.org/wiki/Coffee'
-
-Any parameters that you pass to ``search()`` will be passed to the API. This includes the ``api_key`` parameter, which is required for all requests.
-
-.. _using-api-client-directly:
-
-Using the API Client directly
-^^^^^^^^^
-
-To make this less repetitive, and gain the benefit of connection pooling, let's start using the API Client directly::
-
- >>> client = serpapi.Client(api_key="secret_api_key")
- >>> s = client.search(q="Coffee", engine="google", location="Austin, Texas", hl="en", gl="us")
-
-The ``api_key`` parameter is now automatically passed to all requests made by the client.
-
-
-Concise Tutorial
-----------------
-
-Let's start by searching for ``Coffee`` on Google::
-
- >>> import serpapi
- >>> s = serpapi.search(q="Coffee", engine="google", location="Austin, Texas", hl="en", gl="us")
-
-The ``s`` variable now contains a :class:`SerpResults ` object, which acts just like a standard dictionary, with some convenient functions added on top.
-
-Let's print the first result::
-
- >>> print(s["organic_results"][0]["link"])
- https://en.wikipedia.org/wiki/Coffee
-
-Let's print the title of the first result, but in a more Pythonic way::
-
- >>> print(s["organic_results"][0].get("title"))
- Coffee - Wikipedia
-
-The `SerpApi.com API Documentation `_ contains a list of all the possible parameters that can be passed to the API.
-
-
-API Reference
--------------
-
-.. _api-reference:
-
-This part of the documentation covers all the interfaces of :class:`serpapi` Python module.
-
-.. module:: serpapi
- :platform: Unix, Windows
- :synopsis: SerpApi Python Library
-
-.. autofunction:: serpapi.search
-.. autofunction:: serpapi.search_archive
-.. autofunction:: serpapi.locations
-.. autofunction:: serpapi.account
-
-
-
-Results from SerpApi.com
-------------------------
-
-When a successful search has been executed, the method returns
-a :class:`SerpResults ` object, which acts just like a standard dictionary,
-with some convenient functions added on top.
-
-
-.. code-block:: python
-
- >>> s = serpapi.search(q="Coffee", engine="google", location="Austin, Texas", hl="en", gl="us")
- >>> type(s)
-
-
- >>> s["organic_results"][0]["link"]
- 'https://en.wikipedia.org/wiki/Coffee'
-
- >>> s["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}
-
-Optionally, if you want exactly a dictionary of the entire response, you can use the ``as_dict()`` method::
-
- >>> type(s.as_dict())
-
-
-You can get the next page of results::
-
- >>> type(s.next_page())
-
-
-To iterate over all pages of results, it's recommended to :ref:`use the API Client directly `::
-
- >>> client = serpapi.Client(api_key="secret_api_key")
- >>> search = client.search(q="Coffee", engine="google", location="Austin, Texas", hl="en", gl="us")
- >>> for page in search.yield_pages():
- ... print(page["search_metadata"]["page_number"])
- 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
- 10
-
-
-Here's documentation of the class itself and its methods:
-
-.. autoclass:: serpapi.SerpResults
-
- .. automethod:: SerpResults.next_page
- .. automethod:: SerpResults.yield_pages
- .. autoproperty:: SerpResults.next_page_url
-
-
-API Client
-----------
-
-The primary interface to `serpapi-python` is through the :class:`serpapi.Client` class.
-The primary benefit of using this class is to benefit from Requests' HTTP Connection Pooling.
-This class also alleviates the need to pass an ``api_key``` along with every search made to the platform.
-
-.. autoclass:: serpapi.Client
-
- .. automethod:: Client.search
- .. automethod:: Client.search_archive
- .. automethod:: Client.account
- .. automethod:: Client.locations
-
-
-
-Exceptions
-----------
-
-.. autoexception:: serpapi.SerpApiError
- :members:
-
-.. autoexception:: serpapi.SearchIDNotProvided
- :members:
-
-.. autoexception:: serpapi.HTTPError
- :members:
-
-.. autoexception:: serpapi.HTTPConnectionError
- :members:
-
-
-
-
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
diff --git a/docs/requirements.txt b/docs/requirements.txt
deleted file mode 100644
index 987dd00..0000000
--- a/docs/requirements.txt
+++ /dev/null
@@ -1,53 +0,0 @@
-alabaster==0.7.13
-astroid==2.15.5
-Babel==2.12.1
-bleach==6.0.0
-certifi==2023.5.7
-charset-normalizer==3.2.0
-coverage==7.2.7
-dill==0.3.6
-docutils==0.20.1
-idna==3.4
-imagesize==1.4.1
-importlib-metadata==6.7.0
-iniconfig==2.0.0
-isort==5.12.0
-jaraco.classes==3.2.3
-Jinja2==3.1.2
-keyring==24.2.0
-lazy-object-proxy==1.9.0
-markdown-it-py==3.0.0
-MarkupSafe==2.1.3
-mccabe==0.7.0
-mdurl==0.1.2
-more-itertools==9.1.0
-packaging==23.1
-pkginfo==1.9.6
-platformdirs==3.8.0
-pluggy==1.2.0
-pycodestyle==2.10.0
-Pygments==2.15.1
-pylint==2.17.4
-pytest==7.4.0
-pytest-cov==4.1.0
-readme-renderer==40.0
-requests==2.31.0
-requests-toolbelt==1.0.0
-rfc3986==2.0.0
-rich==13.4.2
-six==1.16.0
-snowballstemmer==2.2.0
-Sphinx==7.0.1
-sphinxcontrib-applehelp==1.0.4
-sphinxcontrib-devhelp==1.0.2
-sphinxcontrib-htmlhelp==2.0.1
-sphinxcontrib-jsmath==1.0.1
-sphinxcontrib-qthelp==1.0.3
-sphinxcontrib-serializinghtml==1.1.5
-tomlkit==0.11.8
-twine==4.0.2
-urllib3==2.0.3
-webencodings==0.5.1
-wrapt==1.15.0
-zipp==3.15.0
--e .
diff --git a/docs/user_guide/00-getting-started.md b/docs/user_guide/00-getting-started.md
new file mode 100644
index 0000000..63e1a43
--- /dev/null
+++ b/docs/user_guide/00-getting-started.md
@@ -0,0 +1,121 @@
+---
+title: "Getting Started"
+description: "Install serpapi, create a client, and run your first search."
+guide-section: "Basics"
+---
+
+# 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
+
+:::{.panel-tabset}
+
+## 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:
+
+:::{.panel-tabset}
+
+## 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](client-usage.md) for response helpers, request options, and archive helpers.
+- Read [Pagination](pagination.md) when collecting more than one page of results.
+- Try [Google Across Countries](../docs/examples/google-across-countries.md) for a practical localization example.
diff --git a/docs/user_guide/01-client-usage.md b/docs/user_guide/01-client-usage.md
new file mode 100644
index 0000000..7cbd6ea
--- /dev/null
+++ b/docs/user_guide/01-client-usage.md
@@ -0,0 +1,168 @@
+---
+title: "Client Usage"
+description: "Use the SerpApi client, module helpers, request options, and response helpers."
+guide-section: "Basics"
+---
+
+# Client Usage
+
+The primary interface is `serpapi.Client`. A client keeps the API key, timeout, and HTTP session configuration together, which is useful for applications and scripts that make more than one request.
+
+## Create a Client
+
+```python
+import os
+import serpapi
+
+client = serpapi.Client(
+ api_key=os.environ["SERPAPI_KEY"],
+ timeout=20,
+)
+```
+
+`timeout` becomes the default request timeout for searches, archive lookups, account calls, and locations calls made by this client.
+
+## Search
+
+Pass engine parameters as keyword arguments:
+
+```python
+results = client.search(engine="google", q="coffee")
+```
+
+You can also pass a dictionary when parameters are already stored in one:
+
+```python
+params = {
+ "engine": "google",
+ "q": "coffee",
+}
+results = client.search(params)
+```
+
+Dictionary parameters and keyword arguments can be mixed. Keyword arguments update the dictionary, which is useful when you start from a saved parameter set:
+
+```python
+params = {"engine": "google", "q": "coffee"}
+results = client.search(params, location="Austin, Texas")
+```
+
+## Module Helpers
+
+For quick scripts, the package exposes module-level helpers:
+
+```python
+import serpapi
+
+results = serpapi.search(
+ api_key="secret_api_key",
+ engine="google",
+ q="coffee",
+)
+```
+
+The helpers use a shared client under the hood. For applications, tests, pagination, and concurrent workloads, prefer creating your own `serpapi.Client`.
+
+## Search Archive
+
+Use `search_archive()` when you have a SerpApi search ID:
+
+```python
+search_id = results["search_metadata"]["id"]
+archived = client.search_archive(search_id=search_id)
+```
+
+If `search_id` is missing, the client raises `serpapi.SearchIDNotProvided`.
+
+## Account and Locations
+
+```python
+account = client.account()
+locations = client.locations(q="Austin", limit=3)
+```
+
+`account()` returns account information for the configured API key. `locations()` returns supported Google locations that match the query; see [Account and Locations](account-and-locations.md) for the local guide and example.
+
+## Request Options
+
+`search()`, `search_archive()`, `account()`, and `locations()` pass these keyword arguments to the underlying `requests` call:
+
+| Option | Use |
+| --- | --- |
+| `timeout` | Override the client timeout for one request. |
+| `proxies` | Send the request through a proxy. |
+| `verify` | Control TLS certificate verification. |
+| `stream` | Stream the HTTP response. |
+| `cert` | Use a client certificate. |
+
+Example:
+
+```python
+results = client.search(
+ engine="google",
+ q="coffee",
+ timeout=10,
+)
+```
+
+See [Request Options](request-options.md) for proxy, TLS, certificate, and per-request timeout examples.
+
+## Response Objects
+
+JSON search responses are returned as `serpapi.SerpResults`. It behaves like a dictionary:
+
+```python
+first = results["organic_results"][0]
+print(first.get("title"))
+print(first.get("link"))
+```
+
+Use `as_dict()` when another library needs a plain dictionary:
+
+```python
+payload = results.as_dict()
+```
+
+If you request `output=html`, the response is plain text instead of `SerpResults`:
+
+```python
+html = client.search(engine="google", q="coffee", output="html")
+print(html[:500])
+```
+
+## Pagination Helpers
+
+For one additional page, call `next_page()`:
+
+```python
+next_results = results.next_page()
+```
+
+To iterate through all available pages, use `yield_pages()`:
+
+```python
+for page_number, page in enumerate(results.yield_pages(max_pages=10), start=1):
+ current = page.get("serpapi_pagination", {}).get("current", page_number)
+ print(current)
+```
+
+See [Pagination](pagination.md) for fuller pagination examples and Google `start` offsets.
+
+## Error Handling
+
+The client raises SerpApi-specific exceptions for common failure modes:
+
+```python
+import serpapi
+
+try:
+ results = client.search(engine="google", q="coffee")
+except serpapi.TimeoutError:
+ print("The request timed out.")
+except serpapi.HTTPConnectionError:
+ print("Could not connect to SerpApi.")
+except serpapi.HTTPError as exc:
+ print(exc.status_code, exc.error)
+```
+
+See [Errors and Timeouts](errors-and-timeouts.md) for status handling guidance.
diff --git a/docs/user_guide/02-parameters-and-engines.md b/docs/user_guide/02-parameters-and-engines.md
new file mode 100644
index 0000000..07af0cd
--- /dev/null
+++ b/docs/user_guide/02-parameters-and-engines.md
@@ -0,0 +1,81 @@
+---
+title: "Parameters and Engines"
+description: "How Python parameters map to SerpApi engines and where to find the full supported list."
+guide-section: "User Guide"
+---
+
+# Parameters and Engines
+
+SerpApi Python forwards search parameters to the SerpApi HTTP API. The package does not keep a separate engine schema, so new engines and engine parameters can be used as soon as they are supported by SerpApi.
+
+## Full Engine and Parameter Reference
+
+Use these SerpApi resources as the source of truth:
+
+- [SerpApi Search API documentation](https://serpapi.com/search-api) lists supported engines and engine-specific parameters.
+- [SerpApi Playground](https://serpapi.com/playground) lets you test a search and copy the exact parameters into Python.
+- [Account and Locations](account-and-locations.md) shows how to find valid `location` values from Python.
+
+The Search API docs include engines such as Google Search, Google Maps, Google Images, Google Shopping, Google Scholar, Google Jobs, Bing, DuckDuckGo, Yahoo, Yandex, Baidu, YouTube, eBay, Walmart, Naver, Apple App Store, Home Depot, and many more. Check the docs for the current full list.
+
+## Passing Parameters
+
+Pass engine parameters as keyword arguments:
+
+```python
+results = client.search(
+ engine="google",
+ q="coffee",
+ location="Austin, Texas",
+ hl="en",
+ gl="us",
+)
+```
+
+You can also pass a dictionary when you already have parameters in one:
+
+```python
+params = {
+ "engine": "google",
+ "q": "coffee",
+ "location": "Austin, Texas",
+ "hl": "en",
+ "gl": "us",
+}
+results = client.search(params)
+```
+
+## Common Google Parameters
+
+These are common Google Search parameters. Other engines have their own parameter names.
+
+| Parameter | Purpose |
+| --- | --- |
+| `engine` | Search engine. Use `google` for Google Search. |
+| `q` | Search query. |
+| `location` | Geographic location for the search. |
+| `google_domain` | Google domain, such as `google.com` or `google.co.in`. |
+| `gl` | Country code for the search. |
+| `hl` | Interface language. |
+| `start` | Result offset for pagination. |
+| `device` | Device type, such as desktop or mobile. |
+| `output` | Response format, usually `json` or `html`. |
+| `async` | Submit a server-side async search. |
+| `no_cache` | Force SerpApi to fetch fresh results. |
+| `zero_trace` | Request zero data retention behavior when enabled for your account. |
+| `json_restrictor` | Return only selected JSON fields from the API response. |
+
+For the full supported list and the exact meaning of each parameter, use the [SerpApi Search API documentation](https://serpapi.com/search-api).
+
+## Engine-Specific Names
+
+Different engines use different query parameter names. For example:
+
+```python
+google = client.search(engine="google", q="coffee")
+ebay = client.search(engine="ebay", _nkw="coffee grinder")
+youtube = client.search(engine="youtube", search_query="coffee brewing")
+walmart = client.search(engine="walmart", query="coffee")
+```
+
+When in doubt, open the engine in the [SerpApi Playground](https://serpapi.com/playground), set up the search, and copy the generated parameters.
diff --git a/docs/user_guide/03-pagination.md b/docs/user_guide/03-pagination.md
new file mode 100644
index 0000000..4c80bac
--- /dev/null
+++ b/docs/user_guide/03-pagination.md
@@ -0,0 +1,85 @@
+---
+title: "Pagination"
+description: "Collect additional pages with SerpResults helpers or engine-specific offsets."
+guide-section: "User Guide"
+---
+
+# Pagination
+
+Many SerpApi responses include pagination metadata. SerpApi Python exposes this through `SerpResults.next_page_url`, `next_page()`, and `yield_pages()`.
+
+## Fetch One More Page
+
+```python
+results = client.search(
+ engine="google",
+ q="coffee",
+ location="Austin, Texas",
+)
+
+next_results = results.next_page()
+
+if next_results:
+ for item in next_results.get("organic_results", []):
+ print(item.get("title"))
+```
+
+`next_page()` returns `None` when the response does not include a next page URL.
+
+## Iterate Through Pages
+
+Use `yield_pages()` when you want the current page plus following pages:
+
+```python
+results = client.search(
+ engine="google",
+ q="coffee",
+ location="Austin, Texas",
+)
+
+for page in results.yield_pages(max_pages=5):
+ for item in page.get("organic_results", []):
+ print(item.get("position"), item.get("title"))
+```
+
+Always set `max_pages` deliberately. Search result pages can change over time and some queries expose many pages.
+
+## Google `start` Offsets
+
+Google Search also supports explicit result offsets:
+
+```python
+for start in [0, 10, 20]:
+ page = client.search(
+ engine="google",
+ q="coffee",
+ location="Austin, Texas",
+ start=start,
+ )
+
+ print("Offset:", start)
+ for item in page.get("organic_results", []):
+ print(item.get("title"))
+```
+
+Use this style when you need deterministic offsets or when you want to parallelize independent pages.
+
+## Store Only What You Need
+
+Search responses can be large. For long crawls or scheduled jobs, extract and store only the fields your application needs:
+
+```python
+records = []
+
+for page in results.yield_pages(max_pages=3):
+ for item in page.get("organic_results", []):
+ records.append({
+ "title": item.get("title"),
+ "link": item.get("link"),
+ "snippet": item.get("snippet"),
+ })
+```
+
+## Pagination Parameters Vary by Engine
+
+`start` is common for Google Search, but other engines may use different pagination parameters. Check the relevant engine page in the [SerpApi Search API documentation](https://serpapi.com/search-api) or build the request in the [SerpApi Playground](https://serpapi.com/playground).
diff --git a/docs/user_guide/04-errors-and-timeouts.md b/docs/user_guide/04-errors-and-timeouts.md
new file mode 100644
index 0000000..b6c66f5
--- /dev/null
+++ b/docs/user_guide/04-errors-and-timeouts.md
@@ -0,0 +1,76 @@
+---
+title: "Errors and Timeouts"
+description: "Handle SerpApi HTTP errors, connection errors, timeouts, and API-level errors."
+guide-section: "User Guide"
+---
+
+# Errors and Timeouts
+
+SerpApi Python wraps common failure modes in package-specific exceptions while preserving useful details from `requests`.
+
+## HTTP Errors
+
+Non-200 responses raise `serpapi.HTTPError`:
+
+```python
+import serpapi
+
+try:
+ results = client.search(engine="google", q="coffee")
+except serpapi.HTTPError as exc:
+ print("Status:", exc.status_code)
+ print("Error:", exc.error)
+```
+
+`exc.status_code` contains the HTTP status code when available. `exc.error` contains the `error` field from SerpApi's JSON response when available.
+
+See [SerpApi API status and error codes](https://serpapi.com/api-status-and-error-codes) for status guidance.
+
+## Connection Errors and Timeouts
+
+```python
+try:
+ results = client.search(engine="google", q="coffee", timeout=10)
+except serpapi.TimeoutError:
+ print("The request timed out.")
+except serpapi.HTTPConnectionError:
+ print("Could not connect to SerpApi.")
+```
+
+Set a default timeout on the client:
+
+```python
+client = serpapi.Client(api_key="secret_api_key", timeout=20)
+```
+
+Override it for one request:
+
+```python
+results = client.search(
+ engine="google",
+ q="coffee",
+ timeout=5,
+)
+```
+
+## Missing Search IDs
+
+`search_archive()` requires a `search_id`:
+
+```python
+try:
+ archived = client.search_archive()
+except serpapi.SearchIDNotProvided:
+ print("Provide search_id from search_metadata.id.")
+```
+
+## API-Level Errors in JSON
+
+Some API responses may include an `error` field in JSON. If your workflow continues after a response is returned, check for that field before using result arrays:
+
+```python
+results = client.search(engine="google", q="coffee")
+
+if "error" in results:
+ raise RuntimeError(results["error"])
+```
diff --git a/docs/user_guide/05-account-and-locations.md b/docs/user_guide/05-account-and-locations.md
new file mode 100644
index 0000000..94fdc5c
--- /dev/null
+++ b/docs/user_guide/05-account-and-locations.md
@@ -0,0 +1,48 @@
+---
+title: "Account and Locations"
+description: "Use account and locations helpers for account metadata and valid Google locations."
+guide-section: "User Guide"
+---
+
+# Account and Locations
+
+The client includes helpers for SerpApi account metadata and Google locations.
+
+## Account
+
+Use `account()` to inspect information for the configured API key:
+
+```python
+import os
+import serpapi
+
+client = serpapi.Client(api_key=os.environ["SERPAPI_KEY"])
+
+account = client.account()
+print(account)
+```
+
+This is useful in diagnostics, internal tooling, and setup checks.
+
+## Locations
+
+Use `locations()` to find supported Google locations:
+
+```python
+locations = client.locations(q="Austin", limit=5)
+
+for location in locations:
+ print(location.get("name"), location.get("canonical_name"))
+```
+
+Then pass the selected location to a search:
+
+```python
+results = client.search(
+ engine="google",
+ q="coffee",
+ location="Austin, Texas, United States",
+)
+```
+
+The [SerpApi Locations API documentation](https://serpapi.com/locations-api) has the full endpoint behavior.
diff --git a/docs/user_guide/06-migrating-from-google-search-results.md b/docs/user_guide/06-migrating-from-google-search-results.md
new file mode 100644
index 0000000..0b62740
--- /dev/null
+++ b/docs/user_guide/06-migrating-from-google-search-results.md
@@ -0,0 +1,115 @@
+---
+title: "Migrating from google-search-results"
+description: "Move from the deprecated google-search-results SDK to the recommended serpapi package."
+guide-section: "Migration"
+---
+
+# Migrating from google-search-results
+
+SerpApi has two Python libraries that use similar import names. For new projects and active integrations, use the recommended `serpapi` package.
+
+## Recommended Package
+
+The new and recommended client is [`serpapi` on PyPI](https://pypi.org/project/serpapi/).
+
+Install it with:
+
+```bash
+pip install serpapi
+```
+
+Use `serpapi.Client`:
+
+```python
+import os
+import serpapi
+
+YOUR_API_KEY = os.environ["SERPAPI_KEY"]
+
+client = serpapi.Client(api_key=YOUR_API_KEY)
+results = client.search(engine="google", q="coffee")
+
+print(results)
+```
+
+This is the package used throughout the current documentation.
+
+## Deprecated Package
+
+The old Python SDK is [`google-search-results` on PyPI](https://pypi.org/project/google-search-results/). It is deprecated for new integrations.
+
+It was installed with:
+
+```bash
+pip install google-search-results
+```
+
+Older code often looks like this:
+
+
+```python
+from serpapi import GoogleSearch
+
+search = GoogleSearch({
+ "q": "coffee",
+ "location": "Austin,Texas",
+ "api_key": "",
+})
+result = search.get_dict()
+```
+
+Do not add this package to new projects.
+
+## Update Your Dependencies
+
+Remove `google-search-results` from your dependency files, such as `requirements.txt`, `pyproject.toml`, `setup.py`, `Pipfile`, or Poetry dependency configuration.
+
+Then add `serpapi` instead:
+
+```bash
+pip install serpapi
+```
+
+Avoid installing both packages in the same environment. They can share the `serpapi` import namespace, which makes migration harder to reason about.
+
+## Update Your Code
+
+Replace `GoogleSearch(...).get_dict()` with `serpapi.Client(...).search(...)`.
+
+Old:
+
+
+```python
+from serpapi import GoogleSearch
+
+search = GoogleSearch({
+ "q": "coffee",
+ "location": "Austin,Texas",
+ "api_key": "",
+})
+result = search.get_dict()
+```
+
+New:
+
+```python
+import os
+import serpapi
+
+client = serpapi.Client(api_key=os.environ["SERPAPI_KEY"])
+results = client.search(
+ engine="google",
+ q="coffee",
+ location="Austin, Texas",
+)
+```
+
+Search parameters use the same SerpApi names, so most request parameter usage can move over directly. Prefer passing them as keyword arguments in new code; dictionaries are still accepted when migration code already has parameters in a mapping.
+
+## Migration Checklist
+
+- Remove `google-search-results` from requirements and dependency files.
+- Install `serpapi` with `pip install serpapi`.
+- Replace `from serpapi import GoogleSearch` with `import serpapi`.
+- Replace `GoogleSearch(params).get_dict()` with `serpapi.Client(api_key=...).search(engine=..., q=..., ...)`.
+- Keep using the [SerpApi Playground](https://serpapi.com/playground) and the [SerpApi API documentation](https://serpapi.com/search-api) to confirm engine parameters.
diff --git a/docs/user_guide/07-async-search-archive.md b/docs/user_guide/07-async-search-archive.md
new file mode 100644
index 0000000..b333ffc
--- /dev/null
+++ b/docs/user_guide/07-async-search-archive.md
@@ -0,0 +1,56 @@
+---
+title: "Async Search Archive"
+description: "Submit server-side async searches and retrieve them later from the Search Archive API."
+guide-section: "Advanced Usage"
+---
+
+# Async Search Archive
+
+SerpApi supports server-side async searches. This is different from Python `asyncio`: you submit a search with `async=true`, receive a search ID, and retrieve the completed search later with the Search Archive API.
+
+## Submit an Async Search
+
+```python
+submitted = client.search(
+ engine="google",
+ q="coffee",
+ location="Austin, Texas",
+ **{"async": True},
+)
+
+search_id = submitted["search_metadata"]["id"]
+print(search_id)
+```
+
+## Retrieve the Search
+
+```python
+archived = client.search_archive(search_id=search_id)
+
+status = archived.get("search_metadata", {}).get("status")
+print(status)
+```
+
+If the search is still queued or processing, wait and call `search_archive()` again:
+
+```python
+import time
+
+while True:
+ archived = client.search_archive(search_id=search_id)
+ status = archived.get("search_metadata", {}).get("status")
+
+ if status == "Success":
+ break
+
+ if status == "Error":
+ raise RuntimeError(archived.get("error", "Search failed"))
+
+ time.sleep(2)
+```
+
+## When to Use Async Searches
+
+Async searches are useful when you want to submit work quickly and collect results later, especially from job queues, scheduled workers, or data pipelines.
+
+Do not combine `async=true` with `no_cache=true`. Use the [SerpApi Search Archive API documentation](https://serpapi.com/search-archive-api) for retention windows and status details.
diff --git a/docs/user_guide/08-threading.md b/docs/user_guide/08-threading.md
new file mode 100644
index 0000000..4ddf2e5
--- /dev/null
+++ b/docs/user_guide/08-threading.md
@@ -0,0 +1,71 @@
+---
+title: "Threading"
+description: "Parallelize independent SerpApi requests with ThreadPoolExecutor."
+guide-section: "Advanced Usage"
+---
+
+# Threading
+
+SerpApi requests are network-bound, so threads are often a simple way to run independent searches concurrently.
+
+## ThreadPoolExecutor Example
+
+```python
+import os
+import serpapi
+
+from concurrent.futures import ThreadPoolExecutor, as_completed
+
+
+API_KEY = os.environ["SERPAPI_KEY"]
+
+
+def search_country(country):
+ client = serpapi.Client(api_key=API_KEY, timeout=20)
+ results = client.search(
+ engine="google",
+ q="best coffee beans",
+ gl=country,
+ hl="en",
+ )
+ return country, results.get("organic_results", [])
+
+
+countries = ["us", "gb", "ca", "au", "in"]
+
+with ThreadPoolExecutor(max_workers=5) as executor:
+ futures = [executor.submit(search_country, country) for country in countries]
+
+ for future in as_completed(futures):
+ country, organic_results = future.result()
+ first = organic_results[0] if organic_results else {}
+ print(country, first.get("title"))
+```
+
+## Practical Guidance
+
+- Keep `max_workers` modest and tune it for your quota, latency, and downstream processing.
+- Handle exceptions per future so one failed request does not hide all other results.
+- Create a client inside each worker when you want clear isolation between threads.
+- Use explicit timeouts so blocked network calls do not stall the whole batch.
+
+## Handling Per-Request Errors
+
+```python
+with ThreadPoolExecutor(max_workers=5) as executor:
+ future_to_country = {
+ executor.submit(search_country, country): country
+ for country in countries
+ }
+
+ for future in as_completed(future_to_country):
+ country = future_to_country[future]
+
+ try:
+ country, organic_results = future.result()
+ except serpapi.SerpApiError as exc:
+ print("Failed:", country, exc)
+ continue
+
+ print("Finished:", country, len(organic_results))
+```
diff --git a/docs/user_guide/09-multiprocessing.md b/docs/user_guide/09-multiprocessing.md
new file mode 100644
index 0000000..f67ba9a
--- /dev/null
+++ b/docs/user_guide/09-multiprocessing.md
@@ -0,0 +1,73 @@
+---
+title: "Multiprocessing"
+description: "Parallelize CPU-heavy or isolated SerpApi workloads with ProcessPoolExecutor."
+guide-section: "Advanced Usage"
+---
+
+# Multiprocessing
+
+Use multiprocessing when each search has heavy CPU-bound post-processing, when you need process isolation, or when your worker code already runs in a process pool. For simple network-bound searches, threads are usually lighter.
+
+## ProcessPoolExecutor Example
+
+```python
+import os
+import serpapi
+
+from concurrent.futures import ProcessPoolExecutor, as_completed
+
+
+def search_country(country):
+ client = serpapi.Client(api_key=os.environ["SERPAPI_KEY"], timeout=20)
+ results = client.search(
+ engine="google",
+ q="best coffee beans",
+ gl=country,
+ hl="en",
+ )
+
+ organic_results = results.get("organic_results", [])
+ return {
+ "country": country,
+ "count": len(organic_results),
+ "first_title": organic_results[0].get("title") if organic_results else None,
+ }
+
+
+if __name__ == "__main__":
+ countries = ["us", "gb", "ca", "au", "in"]
+
+ with ProcessPoolExecutor(max_workers=4) as executor:
+ futures = [executor.submit(search_country, country) for country in countries]
+
+ for future in as_completed(futures):
+ print(future.result())
+```
+
+The `if __name__ == "__main__"` guard is important for multiprocessing, especially on macOS and Windows.
+
+## Practical Guidance
+
+- Create the `serpapi.Client` inside the worker process.
+- Return plain serializable data such as dictionaries, lists, strings, and numbers.
+- Avoid passing open sessions, response objects, or client instances between processes.
+- Set explicit timeouts.
+- Prefer threading for simple concurrent HTTP requests unless CPU-heavy work makes multiprocessing worthwhile.
+
+## Combining Pagination and Processes
+
+For Google Search, independent `start` offsets can be distributed across workers:
+
+```python
+def search_offset(start):
+ client = serpapi.Client(api_key=os.environ["SERPAPI_KEY"], timeout=20)
+ results = client.search(
+ engine="google",
+ q="coffee",
+ location="Austin, Texas",
+ start=start,
+ )
+ return results.get("organic_results", [])
+```
+
+Check the relevant engine docs before parallelizing offsets because pagination parameters vary by engine.
diff --git a/docs/user_guide/10-zero-trace.md b/docs/user_guide/10-zero-trace.md
new file mode 100644
index 0000000..8757cf2
--- /dev/null
+++ b/docs/user_guide/10-zero-trace.md
@@ -0,0 +1,48 @@
+---
+title: "Zero Trace and Data Retention"
+description: "Use zero_trace, no_cache, and async choices intentionally."
+guide-section: "Advanced Usage"
+---
+
+# Zero Trace and Data Retention
+
+SerpApi exposes request parameters for data retention and cache behavior. The Python client passes these parameters through to the API.
+
+## Zero Trace
+
+When enabled for your account, pass `zero_trace=true` to request zero data retention behavior for a search:
+
+```python
+results = client.search(
+ engine="google",
+ q="coffee",
+ location="Austin, Texas",
+ zero_trace=True,
+)
+```
+
+Use this for workloads that require stricter data handling. Zero trace availability and behavior are account-dependent, so confirm details in the [SerpApi Search API documentation](https://serpapi.com/search-api) and your plan.
+
+## Cache Controls
+
+Use `no_cache=true` when you want SerpApi to fetch fresh results instead of using cached results:
+
+```python
+results = client.search(
+ engine="google",
+ q="coffee",
+ no_cache=True,
+)
+```
+
+`no_cache=true` and `async=true` should not be used together.
+
+## Choosing Between Modes
+
+| Need | Parameter |
+| --- | --- |
+| Fresh live results | `no_cache=true` |
+| Submit now and fetch later | `async=true` plus `search_archive()` |
+| Zero data retention behavior | `zero_trace=true` when enabled for your account |
+
+See [Async Search Archive](async-search-archive.md) for async search usage.
diff --git a/docs/user_guide/11-json-restrictor.md b/docs/user_guide/11-json-restrictor.md
new file mode 100644
index 0000000..a6a1470
--- /dev/null
+++ b/docs/user_guide/11-json-restrictor.md
@@ -0,0 +1,136 @@
+---
+title: "JSON Restrictor"
+description: "Use json_restrictor to request only the JSON fields your workflow needs."
+guide-section: "Advanced Usage"
+---
+
+# JSON Restrictor
+
+JSON Restrictor is a SerpApi request parameter that limits the JSON response to selected fields before the response is returned to your Python code. Use it for AI workflows, RAG ingestion, reports, and production jobs that only need a narrow subset of a large engine response.
+
+SerpApi supports `json_restrictor` for all engines. The Python client forwards the selector string with the rest of your search parameters. See the [SerpApi JSON Restrictor documentation](https://serpapi.com/json-restrictor) for the full selector reference.
+
+## Select a Top-Level Section
+
+Return only `organic_results`:
+
+```python
+results = client.search(
+ engine="google",
+ q="coffee",
+ location="Austin, Texas",
+ json_restrictor="organic_results",
+)
+
+for result in results.get("organic_results", []):
+ print(result.get("title"))
+```
+
+## Select Fields From Each Result
+
+Use `[]` to apply a selector to every item in an array. Use a subquery to keep multiple fields from each object:
+
+```python
+results = client.search(
+ engine="google",
+ q="coffee",
+ location="Austin, Texas",
+ json_restrictor="organic_results[].{title, link, snippet}",
+)
+
+for result in results.get("organic_results", []):
+ print(result["title"], result["link"])
+```
+
+The response still uses the normal SerpApi JSON shape, but each matching result only contains the selected fields.
+
+## Select One Item or a Slice
+
+Use an array index when you only need one item:
+
+```python
+results = client.search(
+ engine="google",
+ q="coffee",
+ json_restrictor="organic_results[0]",
+)
+
+first_result = results["organic_results"][0]
+print(first_result["title"])
+```
+
+Use a half-open array slice when you need a fixed number of items:
+
+```python
+results = client.search(
+ engine="google",
+ q="coffee",
+ json_restrictor="organic_results[0:3]",
+)
+```
+
+`organic_results[0:3]` keeps indexes `0`, `1`, and `2`.
+
+## Combine Multiple Selectors
+
+Separate selectors with commas when your workflow needs more than one part of the response:
+
+```python
+results = client.search(
+ engine="google",
+ q="coffee",
+ location="Austin, Texas",
+ json_restrictor="local_map, organic_results[0]",
+)
+
+print(results.get("local_map", {}).get("gps_coordinates"))
+print(results["organic_results"][0]["title"])
+```
+
+## Nested Fields
+
+Selectors can keep nested values while dropping the surrounding fields you do not use:
+
+```python
+results = client.search(
+ engine="google",
+ q="coffee",
+ json_restrictor="organic_results[].{title, sitelinks.inline[].link}",
+)
+```
+
+This is useful when downstream code only needs a compact list of titles and related links.
+
+## Common Selector Patterns
+
+| Need | `json_restrictor` |
+| --- | --- |
+| One top-level section | `organic_results` |
+| First organic result | `organic_results[0]` |
+| First three organic results | `organic_results[0:3]` |
+| One field from every result | `organic_results[].title` |
+| Multiple fields from every result | `organic_results[].{title, snippet}` |
+| Nested fields | `organic_results[].{title, sitelinks.inline[].link}` |
+| Multiple response sections | `local_map, organic_results[0]` |
+
+## Practical Guidance
+
+- Start without `json_restrictor`, inspect the response shape, then add selectors for the fields your workflow actually needs.
+- Keep selectors close to the engine response you tested. Different engines expose different result sections and field names.
+- If you plan to call `next_page()` or `yield_pages()`, include `serpapi_pagination` in the selector so the client can find the next-page URL.
+- If you need a search ID, status, or archive metadata, include `search_metadata`.
+
+For paginated collection, keep both the fields you want and the pagination metadata:
+
+```python
+results = client.search(
+ engine="google",
+ q="coffee",
+ location="Austin, Texas",
+ json_restrictor="organic_results[].{title, link}, serpapi_pagination",
+)
+
+for page in results.yield_pages(max_pages=3):
+ for result in page.get("organic_results", []):
+ print(result["title"], result["link"])
+```
diff --git a/docs/user_guide/12-request-options.md b/docs/user_guide/12-request-options.md
new file mode 100644
index 0000000..862954a
--- /dev/null
+++ b/docs/user_guide/12-request-options.md
@@ -0,0 +1,138 @@
+---
+title: "Request Options"
+description: "Pass requests library options such as timeout, proxies, verify, stream, and cert."
+guide-section: "Advanced Usage"
+---
+
+# Request Options
+
+SerpApi Python separates SerpApi query parameters from options passed to the underlying `requests` library.
+
+SerpApi parameters, such as `engine`, `q`, `location`, `hl`, `gl`, `no_cache`, and `json_restrictor`, are sent to SerpApi as API request parameters. Request options, such as `timeout` and `proxies`, configure the local HTTP request made by the Python client.
+
+## Supported Request Options
+
+The client passes these keyword arguments to `requests.Session.request()`:
+
+| Option | Use |
+| --- | --- |
+| `timeout` | Override the client timeout for one request. |
+| `proxies` | Send the request through HTTP or HTTPS proxies. |
+| `verify` | Control TLS certificate verification. |
+| `stream` | Ask `requests` to stream the HTTP response. |
+| `cert` | Use a client certificate. |
+
+These options are supported by `search()`, `search_archive()`, `account()`, and `locations()`.
+
+## Per-Request Timeout
+
+Set a default timeout when creating the client:
+
+```python
+client = serpapi.Client(api_key="secret_api_key", timeout=20)
+```
+
+Override it for a single request:
+
+```python
+results = client.search(
+ engine="google",
+ q="coffee",
+ timeout=5,
+)
+```
+
+`timeout=5` is passed to `requests`; it is not sent to SerpApi as a search parameter.
+
+## Proxies
+
+Pass a `requests`-style proxies dictionary:
+
+
+```python
+results = client.search(
+ engine="google",
+ q="coffee",
+ proxies={
+ "https": "http://proxy.example.com:8080",
+ },
+)
+```
+
+Keep proxy credentials in environment variables or your secret manager rather than hardcoding them in source files.
+
+## TLS Verification
+
+By default, `requests` verifies TLS certificates. You can pass a custom CA bundle path:
+
+
+```python
+results = client.search(
+ engine="google",
+ q="coffee",
+ verify="/path/to/ca-bundle.pem",
+)
+```
+
+Only disable verification for controlled local debugging:
+
+
+```python
+results = client.search(
+ engine="google",
+ q="coffee",
+ verify=False,
+)
+```
+
+Do not use `verify=False` in production code.
+
+## Client Certificates
+
+Pass a client certificate path, or a `(cert, key)` tuple, using `cert`:
+
+
+```python
+results = client.search(
+ engine="google",
+ q="coffee",
+ cert=("/path/to/client-cert.pem", "/path/to/client-key.pem"),
+)
+```
+
+## Combining Search Parameters and Request Options
+
+Request options can be used alongside normal SerpApi parameters:
+
+```python
+results = client.search(
+ engine="google",
+ q="coffee",
+ location="Austin, Texas",
+ hl="en",
+ gl="us",
+ json_restrictor="organic_results[].{title, link}",
+ timeout=10,
+)
+```
+
+The client handles this in two steps:
+
+- `timeout`, `proxies`, `verify`, `stream`, and `cert` are passed to `requests`.
+- All remaining keyword arguments are sent to SerpApi as API parameters.
+
+If you pass a parameter dictionary and keyword arguments together, the remaining keyword arguments update the dictionary before the request is sent:
+
+```python
+params = {"engine": "google", "q": "coffee"}
+results = client.search(params, location="Austin, Texas", timeout=10)
+```
+
+In this example, `location` is added to the SerpApi request parameters, while `timeout` is passed to `requests`.
+
+When you want to keep the original dictionary unchanged, pass a copy:
+
+```python
+params = {"engine": "google", "q": "coffee"}
+results = client.search(params.copy(), location="Austin, Texas")
+```
diff --git a/great-docs.yml b/great-docs.yml
new file mode 100644
index 0000000..65fc7ee
--- /dev/null
+++ b/great-docs.yml
@@ -0,0 +1,150 @@
+display_name: SerpApi Python
+module: serpapi
+parser: sphinx
+dynamic: true
+
+repo: https://github.com/serpapi/serpapi-python
+site_url: https://serpapi.github.io/serpapi-python/
+github_style: icon
+pypi: true
+
+source:
+ enabled: true
+ branch: master
+ path: serpapi
+ placement: title
+
+authors:
+ - name: SerpApi
+ role: Author
+ email: support@serpapi.com
+ homepage: https://serpapi.com
+
+logo:
+ light: assets/serpapi-logo.svg
+ dark: assets/serpapi-logo-dark.svg
+ alt: SerpApi
+ height: 32px
+ href: index.html
+
+favicon: assets/serpapi-icon.png
+
+hero:
+ enabled: false
+ logo: false
+ name: SerpApi Python
+ tagline: Official Python client for SerpApi search data.
+ badges: auto
+
+homepage: index
+user_guide: docs/user_guide
+sections:
+ - title: Examples
+ dir: docs/examples
+ index: true
+ sidebar_groups:
+ - section: Search Engines
+ contents:
+ - google-across-countries.md
+ - bing-search.md
+ - duckduckgo-search.md
+ - baidu-search.md
+ - section: AI Answers
+ contents:
+ - google-ai-overview.md
+ - section: Local and Maps
+ contents:
+ - google-maps-local-business.md
+ - google-local-services.md
+ - section: Shopping and Marketplaces
+ contents:
+ - google-shopping-products.md
+ - google-shopping-price-monitoring.md
+ - amazon-product-search.md
+ - walmart-product-search.md
+ - ebay-product-listings.md
+ - home-depot-product-search.md
+ - section: Travel and Hospitality
+ contents:
+ - google-flights-travel.md
+ - tripadvisor-travel-search.md
+ - section: Finance, Trends, Jobs, and Events
+ contents:
+ - google-finance-market-data.md
+ - google-trends-demand.md
+ - google-jobs-listings.md
+ - google-events-discovery.md
+ - section: Media, Apps, and Research
+ contents:
+ - youtube-video-search.md
+ - google-images-search.md
+ - google-scholar-research.md
+ - google-play-store-apps.md
+markdown_pages: true
+pre_render:
+ - scripts/build_llms_txt.py
+dark_mode_toggle: true
+
+accent_color:
+ light: "#377FEA"
+ dark: "#38BDF8"
+navbar_color:
+ light: "#FFFFFF"
+ dark: "#111827"
+
+site:
+ theme: flatly
+ toc: true
+ toc-depth: 2
+ language: en
+ show_dates: false
+ show_author: false
+
+include_in_header:
+ - text: ''
+ - text: ''
+
+changelog:
+ enabled: false
+
+skill:
+ enabled: false
+
+sidebar_filter:
+ enabled: true
+ min_items: 8
+
+inline_methods: true
+exclude:
+ - HTTPClient
+ - http
+ - models
+ - textui
+ - utils
+ - core
+ - requests
+ - exceptions
+ - SerpResults.__getstate__
+ - SerpResults.__setstate__
+ - SerpResults.__repr__
+ - SerpResults.from_http_response
+ - http.raise_for_status
+ - models.prettify_json
+ - textui.prettify_json
+
+reference:
+ - title: Search Client
+ desc: Main entry points for making requests and working with responses.
+ contents:
+ - Client
+ - SerpResults
+
+ - title: Exceptions
+ desc: Errors raised by the client for API, HTTP, connection, and timeout failures.
+ contents:
+ - SerpApiError
+ - APIKeyNotProvided
+ - SearchIDNotProvided
+ - HTTPError
+ - HTTPConnectionError
+ - TimeoutError
diff --git a/index.md b/index.md
new file mode 120000
index 0000000..e892330
--- /dev/null
+++ b/index.md
@@ -0,0 +1 @@
+docs/index.md
\ No newline at end of file
diff --git a/pyproject.toml b/pyproject.toml
index 0df45a5..eee4743 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -39,6 +39,7 @@ classifiers = [
[project.optional-dependencies]
color = ["pygments"]
test = ["pytest"]
+docs = ["great-docs>=0.12; python_version >= '3.11'"]
[project.urls]
Homepage = "https://github.com/serpapi/serpapi-python"
@@ -52,4 +53,6 @@ version = { attr = "serpapi.__version__.__version__" }
exclude = ["tests", "tests.*"]
[tool.pytest.ini_options]
-testpaths = ["tests"]
+testpaths = ["tests", "serpapi"]
+addopts = "--doctest-modules"
+doctest_optionflags = ["ELLIPSIS", "NORMALIZE_WHITESPACE"]
diff --git a/scripts/build_llms_txt.py b/scripts/build_llms_txt.py
new file mode 100755
index 0000000..23ead81
--- /dev/null
+++ b/scripts/build_llms_txt.py
@@ -0,0 +1,168 @@
+#!/usr/bin/env python3
+"""Build a useful compact llms.txt for the docs site.
+
+Great Docs generates llms.txt from the API reference only. For SerpApi Python,
+the compact LLM entry point is more useful when it includes the homepage and
+getting-started flow before the reference links.
+"""
+
+from __future__ import annotations
+
+import posixpath
+import re
+from pathlib import Path
+
+
+def find_paths() -> tuple[Path, Path]:
+ script_path = Path(__file__).resolve()
+
+ if script_path.parent.name == "scripts" and script_path.parent.parent.name == "great-docs":
+ build_dir = script_path.parent.parent
+ repo_root = build_dir.parent
+ else:
+ repo_root = script_path.parent.parent
+ build_dir = repo_root / "great-docs"
+
+ return repo_root, build_dir
+
+
+def read_text(path: Path) -> str:
+ return path.read_text(encoding="utf-8")
+
+
+def strip_frontmatter(text: str) -> str:
+ lines = text.splitlines()
+ output: list[str] = []
+ index = 0
+
+ while index < len(lines):
+ if lines[index].strip() == "---":
+ end = index + 1
+ while end < len(lines) and lines[end].strip() != "---":
+ end += 1
+ if end < len(lines):
+ index = end + 1
+ continue
+
+ output.append(lines[index])
+ index += 1
+
+ return "\n".join(output).strip()
+
+
+def clean_markdown(text: str) -> str:
+ text = strip_frontmatter(text)
+ text = re.sub(r"]*>.*?\s*", "", text, flags=re.DOTALL | re.IGNORECASE)
+ text = re.sub(
+ r'
.*?
\s*',
+ "",
+ text,
+ flags=re.DOTALL | re.IGNORECASE,
+ )
+ text = re.sub(r"^:::\s*\{[^}]+\}\s*$", "", text, flags=re.MULTILINE)
+ text = re.sub(r"^:::\s*$", "", text, flags=re.MULTILINE)
+ text = re.sub(r"\n{3,}", "\n\n", text)
+ return text.strip()
+
+
+def demote_headings(text: str) -> str:
+ return re.sub(
+ r"^(#{1,5})(\s+)",
+ lambda match: f"#{match.group(1)}{match.group(2)}",
+ text,
+ flags=re.MULTILINE,
+ )
+
+
+def site_url_from_config(config_path: Path) -> str:
+ if not config_path.exists():
+ return ""
+
+ match = re.search(r"^site_url:\s*(.+?)\s*$", read_text(config_path), flags=re.MULTILINE)
+ if not match:
+ return ""
+
+ site_url = match.group(1).strip().strip('"').strip("'")
+ return site_url if site_url.endswith("/") else f"{site_url}/"
+
+
+def normalize_links(text: str, *, site_url: str, base_path: str = "") -> str:
+ def replace(match: re.Match[str]) -> str:
+ target = match.group(1).strip()
+ if re.match(r"^(?:[a-z][a-z0-9+.-]*:|#)", target, flags=re.IGNORECASE):
+ return f"]({target})"
+
+ path = target[2:] if target.startswith("./") else target
+ joined = posixpath.normpath(posixpath.join(base_path, path))
+ if joined == ".":
+ joined = ""
+
+ joined = re.sub(r"\.q?md($|#)", r".html\1", joined)
+ return f"]({site_url}{joined})" if site_url else f"]({joined})"
+
+ return re.sub(r"\]\(([^)]+)\)", replace, text)
+
+
+def api_reference_from_default(default_llms: str) -> str:
+ marker = "### API Reference"
+ if marker not in default_llms:
+ return ""
+
+ api_reference = default_llms.split(marker, 1)[1].strip()
+ api_reference = re.sub(r"^####(\s+)", r"###\1", api_reference, flags=re.MULTILINE)
+ return api_reference
+
+
+def main() -> None:
+ repo_root, build_dir = find_paths()
+ site_url = site_url_from_config(repo_root / "great-docs.yml")
+
+ index = clean_markdown(read_text(repo_root / "docs" / "index.md"))
+ getting_started = clean_markdown(
+ read_text(repo_root / "docs" / "user_guide" / "00-getting-started.md")
+ )
+ getting_started = re.sub(r"^#\s+Getting Started\s*", "", getting_started).strip()
+
+ index = demote_headings(normalize_links(index, site_url=site_url))
+ getting_started = demote_headings(
+ normalize_links(getting_started, site_url=site_url, base_path="user-guide")
+ )
+
+ api_reference = api_reference_from_default(read_text(build_dir / "llms.txt"))
+
+ lines = [
+ "# SerpApi Python",
+ "",
+ "> Official Python client for SerpApi search data in applications, AI workflows, RAG, and data pipelines.",
+ "",
+ "## Homepage",
+ "",
+ index,
+ "",
+ "## Getting Started",
+ "",
+ getting_started,
+ "",
+ ]
+
+ if api_reference:
+ lines.extend(["## API Reference", "", api_reference, ""])
+
+ if site_url:
+ lines.extend(
+ [
+ "## More LLM Context",
+ "",
+ f"- [Full LLM documentation]({site_url}llms-full.txt)",
+ f"- [Documentation homepage]({site_url}index.html)",
+ "",
+ ]
+ )
+
+ output = "\n".join(lines).strip() + "\n"
+ (build_dir / "llms.txt").write_text(output, encoding="utf-8")
+ print("Updated llms.txt with homepage and getting-started content")
+
+
+if __name__ == "__main__":
+ main()
diff --git a/serpapi/core.py b/serpapi/core.py
index 7d4454a..6ddbc88 100644
--- a/serpapi/core.py
+++ b/serpapi/core.py
@@ -4,23 +4,13 @@
class Client(HTTPClient):
- """A class that handles API requests to SerpApi in a user–friendly manner.
+ """A class that handles API requests to SerpApi in a user-friendly manner.
- :param api_key: The API Key to use for SerpApi.com.
-
- Please provide ``api_key`` when instantiating this class. We recommend storing this in an environment variable, like so:
-
- .. code-block:: bash
-
- $ export SERPAPI_KEY=YOUR_API_KEY
-
- .. code-block:: python
-
- import os
- import serpapi
-
- serpapi = serpapi.Client(api_key=os.environ["SERPAPI_KEY"])
+ Store your API key in an environment variable, then create a client with
+ ``serpapi.Client(api_key=os.environ["SERPAPI_KEY"])``.
+ :param api_key: The API Key to use for SerpApi.com.
+ :param timeout: The default timeout to use for requests.
"""
DASHBOARD_URL = "https://serpapi.com/dashboard"
@@ -32,30 +22,16 @@ def __repr__(self):
return ""
def search(self, params: dict = None, **kwargs):
- """Fetch a page of results from SerpApi. Returns a :class:`SerpResults ` object, or unicode text (*e.g.* if ``'output': 'html'`` was passed).
-
- The following three calls are equivalent:
-
- .. code-block:: python
-
- >>> s = serpapi.search(q="Coffee", location="Austin, Texas, United States")
-
- .. code-block:: python
-
- >>> params = {"q": "Coffee", "location": "Austin, Texas, United States"}
- >>> s = serpapi.search(**params)
-
- .. code-block:: python
+ """Fetch a page of results from SerpApi.
- >>> params = {"q": "Coffee", "location": "Austin, Texas, United States"}
- >>> s = serpapi.search(params)
+ Returns a ``serpapi.SerpResults`` object for JSON responses, or text
+ when ``output="html"`` is requested. Prefer passing SerpApi engine
+ parameters as keyword arguments. A parameter dictionary is also accepted
+ when your code already has parameters in a mapping.
- :param q: typically, this is the parameter for the search engine query.
- :param engine: the search engine to use. Defaults to ``google``.
- :param output: the output format desired (``html`` or ``json``). Defaults to ``json``.
- :param api_key: the API Key to use for SerpApi.com.
- :param **: any additional parameters to pass to the API.
+ :param params: Optional mapping of SerpApi search parameters such as ``engine``, ``q``, ``location``, and ``output``.
+ :param kwargs: Additional SerpApi parameters or request options. ``timeout``, ``proxies``, ``verify``, ``stream``, and ``cert`` are passed to the underlying HTTP request.
**Learn more**: https://serpapi.com/search-api
@@ -79,10 +55,8 @@ def search(self, params: dict = None, **kwargs):
def search_archive(self, params: dict = None, **kwargs):
"""Get a result from the SerpApi Search Archive API.
- :param search_id: the Search ID of the search to retrieve from the archive.
- :param api_key: the API Key to use for SerpApi.com.
- :param output: the output format desired (``html`` or ``json``). Defaults to ``json``.
- :param **: any additional parameters to pass to the API.
+ :param params: Archive parameters. Must include ``search_id``.
+ :param kwargs: Additional archive parameters or request options. ``timeout``, ``proxies``, ``verify``, ``stream``, and ``cert`` are passed to the underlying HTTP request.
**Learn more**: https://serpapi.com/search-archive-api
"""
@@ -112,9 +86,8 @@ def locations(self, params: dict = None, **kwargs):
"""Get a list of supported Google locations.
- :param q: restricts your search to locations that contain the supplied string.
- :param limit: limits the number of locations returned.
- :param **: any additional parameters to pass to the API.
+ :param params: Location API parameters such as ``q`` and ``limit``.
+ :param kwargs: Additional location parameters or request options. ``timeout``, ``proxies``, ``verify``, ``stream``, and ``cert`` are passed to the underlying HTTP request.
**Learn more**: https://serpapi.com/locations-api
"""
@@ -142,8 +115,8 @@ def locations(self, params: dict = None, **kwargs):
def account(self, params: dict = None, **kwargs):
"""Get SerpApi account information.
- :param api_key: the API Key to use for SerpApi.com.
- :param **: any additional parameters to pass to the API.
+ :param params: Account API parameters.
+ :param kwargs: Additional account parameters or request options. ``timeout``, ``proxies``, ``verify``, ``stream``, and ``cert`` are passed to the underlying HTTP request.
**Learn more**: https://serpapi.com/account-api
"""
diff --git a/serpapi/models.py b/serpapi/models.py
index 0aa7720..c7ca647 100644
--- a/serpapi/models.py
+++ b/serpapi/models.py
@@ -10,13 +10,6 @@
class SerpResults(UserDict):
"""A dictionary-like object that represents the results of a SerpApi request.
- .. code-block:: python
-
- >>> search = serpapi.search(q="Coffee", location="Austin, Texas, United States")
-
- >>> print(search["search_metadata"].keys())
- dict_keys(['id', 'status', 'json_endpoint', 'created_at', 'processed_at', 'google_url', 'raw_html_file', 'total_time_taken'])
-
An instance of this class is returned if the response is a valid JSON object.
It can be used like a dictionary, but also has some additional methods.
"""
@@ -40,7 +33,10 @@ def __repr__(self):
def as_dict(self):
"""Returns the data as a standard Python dictionary.
- This can be useful when using ``json.dumps(search), for example."""
+
+ This can be useful when passing results to libraries that expect a
+ plain ``dict``.
+ """
return self.data.copy()
@@ -85,7 +81,7 @@ def yield_pages(self, max_pages=1_000):
def from_http_response(cls, r, *, client=None):
"""Construct a SerpResults object from an HTTP response.
- :param assert_200: if ``True`` (default), raise an exception if the status code is not 200.
+ :param r: The HTTP response to parse.
:param client: the Client instance which was used to send this request.
An instance of this class is returned if the response is a valid JSON object.
diff --git a/tests/test_docs_examples.py b/tests/test_docs_examples.py
new file mode 100644
index 0000000..efbc49b
--- /dev/null
+++ b/tests/test_docs_examples.py
@@ -0,0 +1,57 @@
+import os
+import re
+from pathlib import Path
+
+import pytest
+import serpapi
+
+
+ROOT = Path(__file__).resolve().parents[1]
+PYTHON_BLOCK_RE = re.compile(
+ r"(?P\s*)?```python\n(?P.*?)```",
+ re.DOTALL,
+)
+API_KEY = os.environ.get("SERPAPI_KEY") or os.environ.get("API_KEY")
+
+
+def docs_pages():
+ return [
+ ROOT / "README.md",
+ ROOT / "docs" / "index.md",
+ *sorted((ROOT / "docs" / "user_guide").glob("*.md")),
+ *sorted((ROOT / "docs" / "examples").glob("*.md")),
+ ]
+
+
+def runnable_block(block):
+ if API_KEY is None:
+ return block
+
+ return (
+ block
+ .replace('"secret_api_key"', repr(API_KEY))
+ .replace("'secret_api_key'", repr(API_KEY))
+ )
+
+
+@pytest.mark.skipif(API_KEY is None, reason="SERPAPI_KEY or API_KEY is required")
+@pytest.mark.parametrize("path", docs_pages(), ids=lambda path: path.relative_to(ROOT).as_posix())
+def test_markdown_python_blocks_execute(path, monkeypatch):
+ monkeypatch.setenv("SERPAPI_KEY", API_KEY)
+ monkeypatch.setenv("API_KEY", API_KEY)
+
+ blocks = list(PYTHON_BLOCK_RE.finditer(path.read_text(encoding="utf-8")))
+ assert blocks, f"{path} has no Python examples"
+
+ namespace = {
+ "__name__": "docs_examples",
+ "client": serpapi.Client(api_key=API_KEY, timeout=20),
+ "os": os,
+ "serpapi": serpapi,
+ }
+ for number, block in enumerate(blocks, start=1):
+ if block.group("skip"):
+ continue
+
+ code = runnable_block(block.group("code"))
+ exec(compile(code, f"{path}::python-block-{number}", "exec"), namespace)