serpapi 1.1.0__tar.gz → 1.1.2__tar.gz

serpapi-1.1.2/.readthedocs.yaml

@@ -0,0 +1,27 @@
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.13"
+  jobs:
+    pre_build:
+      - python -m scripts.check_docs_revision
+    post_build:
+      - python -m scripts.check_docs_revision
+
+sphinx:
+  configuration: docs/conf.py
+  fail_on_warning: true
+
+formats:
+  - pdf
+  - epub
+
+python:
+  install:
+    - method: uv
+      command: pip
+      path: .
+      extras:
+        - docs

serpapi-1.1.2/CONTRIBUTING.md

@@ -0,0 +1,183 @@
+# Contributing
+
+Bug reports and pull requests are welcome on GitHub. Run commands from the repository root.
+
+## Development setup
+
+Use Python 3.13 to work on the package and its documentation. The SDK CI also tests Python 3.8 through 3.14. Create a virtual environment and install the package with its test and documentation dependencies:
+
+```sh
+uv venv --python 3.13
+uv pip install -e '.[test,docs]'
+```
+
+The editable install uses the Python files in your checkout, so source changes take effect without reinstalling the package.
+
+Activate the environment on macOS or Linux:
+
+```sh
+source .venv/bin/activate
+```
+
+On Windows PowerShell:
+
+```powershell
+.\.venv\Scripts\Activate.ps1
+```
+
+The commands below use `python` from that environment.
+
+## Testing
+
+### Checks that need no API key
+
+These tests cover response parsing, image uploads with simulated responses, timeouts, exceptions, documentation syntax, and the example runner:
+
+```sh
+python -m pytest tests/test_output_formats.py tests/test_image_upload.py tests/test_timeout.py tests/test_exceptions.py tests/test_docs_examples.py tests/test_docs_example_runner.py -k 'not live' -q
+```
+
+The file list limits this command to tests that make no external requests. Applying `-k 'not live'` to the entire suite is not enough to run offline: some SDK integration tests do not have `live` in their names.
+
+### SDK integration tests
+
+Set `API_KEY` in your shell or editor's run configuration before running integration tests. Documentation examples also accept `SERPAPI_KEY`, but the shared SDK fixtures require `API_KEY`. If you already have `SERPAPI_KEY` set, copy it to `API_KEY` in the same shell:
+
+```sh
+export API_KEY="$SERPAPI_KEY"
+```
+
+In PowerShell, use `$env:API_KEY = $env:SERPAPI_KEY`. Keep real keys out of source files and commits.
+
+To match the test selection in the SDK CI workflow:
+
+```sh
+python -m pytest tests --ignore-glob='tests/test_docs_*.py' -k 'not example' -q
+```
+
+This includes live account, location, search, and pagination checks. To run every discovered test, including the standalone engine examples and documentation examples:
+
+```sh
+python -m pytest -q
+```
+
+Both commands make real SerpApi requests. The full suite can use more searches than a test run limited to the files you changed. PR CI also runs the standalone engine examples on Python 3.14. Documentation tests run in the package and documentation release workflows on release tags, and in manual documentation runs on `master`.
+
+### Testing documentation examples
+
+The tests discover Python code blocks in the README and all Markdown pages under `docs/`. They run each page as a separate script against SerpApi, including the multiprocessing example's worker processes. The Lens upload examples use the repository's PNG icon as `image.png`. Each page has a five-minute limit, and HTTP errors or JSON responses containing an `error` fail the check even if the example catches the exception.
+
+With `SERPAPI_KEY` or `API_KEY` set in your environment, run:
+
+```sh
+python -m pytest tests/test_docs_examples.py --require-docs-key -q
+```
+
+The `--require-docs-key` option fails if neither key is set. Without that option, local runs skip live tests when no key is available. To check syntax and the test runner without making API calls:
+
+```sh
+python -m pytest tests/test_docs_examples.py tests/test_docs_example_runner.py -k 'not live' -q
+```
+
+Code blocks marked with `docs-test: skip` are checked for syntax but not executed. These cover the old `google-search-results` package and examples that require private proxy or certificate settings, or disable TLS verification. Each marker includes its reason.
+
+### Testing documentation publishing
+
+Run the publishing tests locally with:
+
+```sh
+python -m pytest tests/test_docs_publishing.py -q
+```
+
+These tests use simulated RTD responses to check outgoing HTTP requests, CI event and commit checks, version selection, polling, and cleanup after failures. They need no API keys and do not publish documentation. In CI, they run only in the Documentation workflow on Python 3.13, before the documentation build and publication. The SDK and PyPI release workflows exclude this file. RTD checks the actual checkout with `scripts.check_docs_revision` before and after building, without rerunning the publishing tests.
+
+### Running a single test or example
+
+Run one test file while working on that part of the package:
+
+```sh
+python -m pytest tests/test_output_formats.py -q
+```
+
+To list documentation test IDs without running their examples:
+
+```sh
+python -m pytest tests/test_docs_examples.py --collect-only -q
+```
+
+For example, run only the Google Lens upload and search page with:
+
+```sh
+python -m pytest 'tests/test_docs_examples.py::test_documentation_examples_live[docs/examples/google-lens-image-upload.md]' --require-docs-key -q
+```
+
+Use `-x -vv` in place of `-q` to stop at the first failure and show more detail. A syntax failure points to a page and block number. A live failure can come from the example code, an invalid key, exhausted quota, or an upstream API error; inspect the reported engine and error before changing the example.
+
+When adding a documentation example, use a fenced block labelled `python`. Blocks on the same page execute in order and share variables. Avoid hard-coded dates that expire. Use a `docs-test: skip` marker with a reason only when a block cannot run in the test environment, such as one requiring a user's proxy or certificate.
+
+## Building the documentation locally
+
+The documentation uses Sphinx with MyST for Markdown pages and the Read the Docs theme. The development setup above includes its dependencies. Build and serve the HTML site with:
+
+```sh
+python -m sphinx -M html docs docs/_build -W --keep-going
+python -m http.server 8000 --bind 127.0.0.1 --directory docs/_build/html
+```
+
+Open [the local documentation](http://127.0.0.1:8000). After editing a page, rerun the Sphinx build command and refresh your browser. Check the affected page, its code blocks, and the sidebar links. Press Ctrl+C to stop the server.
+
+Sphinx discovers public APIs with autodoc and reads their docstrings without running the search examples. Sidebar order comes from the toctrees in `docs/index.md`, so documentation filenames do not need numeric prefixes. The `-W` option makes warnings fail the build.
+
+CI also builds EPUB. Check it locally with:
+
+```sh
+python -m sphinx -M epub docs docs/_build -W --keep-going
+```
+
+## Building the package
+
+Build the source distribution and wheel with:
+
+```sh
+uv build
+```
+
+The files are written to `dist/`. Documentation sources, this guide, and the logo assets are included in the source distribution (`.tar.gz`) so contributors can build the docs from a source release. The wheel contains only the `serpapi` library and its package metadata. Generated docs and documentation dependencies are not part of a normal installation.
+
+## Documentation publishing
+
+The [documentation workflow](.github/workflows/docs.yml) runs the live examples before building HTML and EPUB when a `v*` release tag is pushed, or when `master` or a release tag is selected for a manual run. It does not run on branch pushes or pull requests.
+
+After the live examples and documentation build pass, the same workflow publishes to Read the Docs for the selected ref. A manual run on `master` updates `latest` without triggering the package release workflow or changing the package version. The publishing job uses the `docs` GitHub environment and its `RTD_API_TOKEN` secret. The SerpApi key stays in GitHub as the existing `API_KEY` repository or organization secret.
+
+The workflow syncs RTD versions, activates the requested version if needed, and waits for the build to finish. `latest` tracks `master`. A release tag has its own version and also updates `stable` when RTD identifies it as the highest stable release. RTD still builds the site from the repository using [.readthedocs.yaml](.readthedocs.yaml); it does not receive the HTML artifact from GitHub. Documentation publishing runs independently of the PyPI release workflow.
+
+Before requesting a build, the workflow creates a temporary RTD environment variable named `DOCS_CI_REVISION`. It contains the tested commit, the permitted versions, and an expiration time. RTD checks this record against its checkout before and after the Sphinx build. A missing, expired, or different revision stops publication. RTD needs no SerpApi key. The workflow removes the temporary record after publishing, including when a build fails. Publishing jobs run one at a time so they cannot overwrite each other's revision record.
+
+### Maintainer setup
+
+Maintainers can configure the existing RTD project and GitHub environment with these steps:
+
+1. In RTD **Settings**, set **Connected repository** to **No connected repository** and keep **Repository URL** set to `https://github.com/serpapi/serpapi-python.git`. Set **Default branch** to `master` and the configuration file path to `.readthedocs.yaml`. The public repository URL lets RTD clone the source without receiving GitHub push events through the GitHub App.
+2. Under RTD **Integrations**, remove incoming GitHub webhook integrations for this project. If an older RTD webhook is also listed in the GitHub repository's **Settings > Webhooks**, disable or remove that webhook. Do not remove integrations for other projects.
+3. Under RTD **Automation Rules**, remove rules that activate new versions or change the default version. The workflow handles release activation. Under **Settings > Pull request builds**, turn off **Build pull requests for this project**. GitHub Actions runs the existing SDK and engine example tests on PRs.
+4. Under RTD **Environment Variables**, remove `API_KEY` or `SERPAPI_KEY` if you added either for docs tests. Do not add the RTD API token here. The workflow manages `DOCS_CI_REVISION` automatically.
+5. Keep `latest` active in **Versions** and use it as the default documentation version during this migration. Existing release tags contain their original docs and build configuration. After the first release containing these changes builds successfully, you can choose `stable` as the default version.
+6. Create an RTD API token in your [RTD profile settings](https://app.readthedocs.org/accounts/tokens/), using an account that maintains the `serpapi-python` project. In GitHub, open the repository's **Settings > Environments**, create an environment named `docs`, and add an environment secret named `RTD_API_TOKEN` with that value. Under **Deployment branches and tags**, select **Selected branches and tags** and add a Branch rule for `master` and a Tag rule for `v*`. Leave required reviewers and wait timers disabled if publishing should run without a manual approval.
+7. Merge the changes to `master`, then push the version tag for the release. In GitHub **Actions > Documentation**, follow **Live documentation examples**, **Build Sphinx documentation**, and **Publish Read the Docs**. The publishing log links to the RTD build. To retry publishing, run the Documentation workflow on the intended release tag, or select `master` to publish updated `latest` docs without a new package release. A manual run on any other branch skips the documentation jobs.
+
+Use GitHub Actions to request builds after this setup. A manual RTD build has no CI revision record and will fail the revision check. If a branch or tag moves between testing and the RTD checkout, rerun the workflow for its current commit. Pushing a `v*` tag also starts the PyPI release workflow, so use an actual package release to test release documentation.
+
+See the [RTD build API](https://docs.readthedocs.com/platform/stable/api/v3.html#build-triggering), [Git integration settings](https://docs.readthedocs.com/platform/stable/reference/git-integration.html), and [GitHub environment settings](https://docs.github.com/en/actions/how-tos/deploy/configure-and-manage-deployments/manage-environments) for the platform setup details.
+
+## Publishing a new release
+
+1. Update the version in `serpapi/__version__.py`.
+2. Push a tag for that version. The release pipeline runs automatically:
+   ```sh
+   git tag v1.2.3
+   git push origin v1.2.3
+   ```
+   This triggers the [release workflow](.github/workflows/release.yml), which tests, builds, and publishes to PyPI, then smoke-tests the published package.
+
+> **Required secret:** `API_KEY` (used by the live documentation examples and the published-package smoke test).

{serpapi-1.1.0 → serpapi-1.1.2}/HISTORY.md

@@ -1,6 +1,27 @@
 Release History
 ===============
 
+1.1.2 (2026-09-15)
+------------------
+
+- Fixed a bug in SerpResults.yield_pages to ensure it does not request more pages than specified by max_pages. The bug
+  caused two network requests to be sent when max_pages was set to 1.
+- Enhancements to test parameters and examples
+
+1.1.1 (2026-09-08)
+------------------
+
+- Enhancements for SerpApi markdown output (`output=md`) support
+- Enhancements for readthedocs documentation: Added user guide, examples, automated publishing to RTD on release.
+
+1.1.0 (2026-08-14)
+------------------
+
+- Add PyPI trusted publishing. PYPI Key is no longer required for publishing the package.
+- Add image upload support (`/image` API) for Google Lens
+- Release workflow: Add an option to manually trigger the release workflow and skip live tests
+- Add more test cases: Locations API, pagination, etc.
+
 1.0.1 (2026-03-18)
 ------------------
 
@@ -22,7 +43,7 @@ Release History
 0.1.5 (2023-11-01)
 ------------------
 
-- Python 3.12 support. 
+- Python 3.12 support.
 
 0.1.4 (2023-10-11)
 ------------------
@@ -32,7 +53,7 @@ Release History
 0.1.3 (2023-10-06)
 ------------------
 
-- Replace deprecated serpapi_pagination.next_link with 'next'. 
+- Replace deprecated serpapi_pagination.next_link with 'next'.
 - Improve documentation: how to use the client directly for pagination searches.
 
 0.1.2 (2023-10-03)

serpapi-1.1.2/MANIFEST.in

@@ -0,0 +1,7 @@
+include README.md CONTRIBUTING.md HISTORY.md LICENSE
+include .readthedocs.yaml
+include scripts/check_docs_revision.py scripts/publish_docs.py
+recursive-include tests *.py
+recursive-include docs *.py *.md *.txt *.css Makefile
+include assets/serpapi-logo.svg assets/serpapi-icon.png
+prune docs/_build

{serpapi-1.1.0/serpapi.egg-info → serpapi-1.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: serpapi
-Version: 1.1.0
+Version: 1.1.2
 Summary: The official Python client for SerpApi.com.
 Author-email: SerpApi <support@serpapi.com>
 License: MIT
@@ -33,6 +33,11 @@ Provides-Extra: color
 Requires-Dist: pygments; extra == "color"
 Provides-Extra: test
 Requires-Dist: pytest; extra == "test"
+Provides-Extra: docs
+Requires-Dist: sphinx<9,>=8.2; python_version >= "3.11" and extra == "docs"
+Requires-Dist: myst-parser<5,>=4; python_version >= "3.11" and extra == "docs"
+Requires-Dist: sphinx-design<1,>=0.6; python_version >= "3.11" and extra == "docs"
+Requires-Dist: sphinx-rtd-theme<4,>=3.1; python_version >= "3.11" and extra == "docs"
 Dynamic: license-file
 
 # SerpApi Python Library & Package
@@ -116,6 +121,22 @@ Documentation is [available on Read the Docs](https://serpapi-python.readthedocs
 
 Change history is [available on GitHub](https://github.com/serpapi/serpapi-python/blob/master/HISTORY.md).
 
+### Markdown output for AI agents
+
+For AI agents and LLM workflows, use `output="md"`. It returns search results with clean headings, links, and tables while using roughly half the tokens of JSON on average.
+
+```python
+markdown = client.search({
+    "engine": "google",
+    "q": "coffee",
+    "output": "md",
+})
+```
+
+Markdown works across SerpApi APIs and is returned as a plain Python string. See [Markdown Output for AI Agents](https://serpapi.com/markdown-output.md) for details.
+
+Raw HTML is also available with `output="html"` and is returned as a plain Python string.
+
 ## Basic Examples in Python
 
 ### Search Bing
@@ -217,7 +238,7 @@ import serpapi
 client = serpapi.Client(api_key=os.getenv("API_KEY"))
 results = client.search({
     'engine': 'home_depot',
-    'q': 'table',
+    'q': 'chair',
 })
 ```
 - API Documentation: [serpapi.com/home-depot-search-api](https://serpapi.com/home-depot-search-api)
@@ -330,11 +351,10 @@ results = client.search({
 })
 ```
 
-To search a local image, upload it first and pass its temporary `image_id` to
-Google Lens:
+To search a local image, place a file named `image.png` in your working directory, upload it, and pass its temporary `image_id` to Google Lens:
 
 ```python
-upload = client.upload_image("/path/to/image.png")
+upload = client.upload_image("image.png")
 results = client.search({
     "engine": "google_lens",
     "image_id": upload["image_id"],
@@ -346,19 +366,6 @@ Uploaded images can be JPG/JPEG, PNG, or WebP files up to 500 KB. The returned
 
 - API Documentation: [Google Lens image uploads](https://serpapi.com/google-lens-upload-an-image), [Image API](https://serpapi.com/image-api)
 
-### Search Google Events
-```python
-import os
-import serpapi
-
-client = serpapi.Client(api_key=os.getenv("API_KEY"))
-results = client.search({
-    'engine': 'google_events',
-    'q': 'Events in Austin',
-})
-```
-- API Documentation: [serpapi.com/google-events-api](https://serpapi.com/google-events-api)
-
 ### Search Google Local Services
 ```python
 import os
@@ -398,7 +405,7 @@ import serpapi
 client = serpapi.Client(api_key=os.getenv("API_KEY"))
 results = client.search({
     'engine': 'google_jobs',
-    'q': 'coffee',
+    'q': 'software engineer',
 })
 ```
 - API Documentation: [serpapi.com/google-jobs-api](https://serpapi.com/google-jobs-api)
@@ -437,16 +444,4 @@ MIT License.
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub. Once dependencies are installed, you can run the tests with `pytest`.
-
-## Publishing a new release
-
-1. Update the version in `serpapi/__version__.py`.
-2. Push a tag — the release pipeline runs automatically:
-   ```sh
-   git tag v1.2.3
-   git push origin v1.2.3
-   ```
-   This triggers the [release workflow](.github/workflows/release.yml), which tests, builds, and publishes to PyPI, then smoke-tests the published package.
-
-> **Required secret:** `API_KEY` (used in smoke-test live search).
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, testing, and publishing instructions.

{serpapi-1.1.0 → serpapi-1.1.2}/README.md

@@ -79,6 +79,22 @@ Documentation is [available on Read the Docs](https://serpapi-python.readthedocs
 
 Change history is [available on GitHub](https://github.com/serpapi/serpapi-python/blob/master/HISTORY.md).
 
+### Markdown output for AI agents
+
+For AI agents and LLM workflows, use `output="md"`. It returns search results with clean headings, links, and tables while using roughly half the tokens of JSON on average.
+
+```python
+markdown = client.search({
+    "engine": "google",
+    "q": "coffee",
+    "output": "md",
+})
+```
+
+Markdown works across SerpApi APIs and is returned as a plain Python string. See [Markdown Output for AI Agents](https://serpapi.com/markdown-output.md) for details.
+
+Raw HTML is also available with `output="html"` and is returned as a plain Python string.
+
 ## Basic Examples in Python
 
 ### Search Bing
@@ -180,7 +196,7 @@ import serpapi
 client = serpapi.Client(api_key=os.getenv("API_KEY"))
 results = client.search({
     'engine': 'home_depot',
-    'q': 'table',
+    'q': 'chair',
 })
 ```
 - API Documentation: [serpapi.com/home-depot-search-api](https://serpapi.com/home-depot-search-api)
@@ -293,11 +309,10 @@ results = client.search({
 })
 ```
 
-To search a local image, upload it first and pass its temporary `image_id` to
-Google Lens:
+To search a local image, place a file named `image.png` in your working directory, upload it, and pass its temporary `image_id` to Google Lens:
 
 ```python
-upload = client.upload_image("/path/to/image.png")
+upload = client.upload_image("image.png")
 results = client.search({
     "engine": "google_lens",
     "image_id": upload["image_id"],
@@ -309,19 +324,6 @@ Uploaded images can be JPG/JPEG, PNG, or WebP files up to 500 KB. The returned
 
 - API Documentation: [Google Lens image uploads](https://serpapi.com/google-lens-upload-an-image), [Image API](https://serpapi.com/image-api)
 
-### Search Google Events
-```python
-import os
-import serpapi
-
-client = serpapi.Client(api_key=os.getenv("API_KEY"))
-results = client.search({
-    'engine': 'google_events',
-    'q': 'Events in Austin',
-})
-```
-- API Documentation: [serpapi.com/google-events-api](https://serpapi.com/google-events-api)
-
 ### Search Google Local Services
 ```python
 import os
@@ -361,7 +363,7 @@ import serpapi
 client = serpapi.Client(api_key=os.getenv("API_KEY"))
 results = client.search({
     'engine': 'google_jobs',
-    'q': 'coffee',
+    'q': 'software engineer',
 })
 ```
 - API Documentation: [serpapi.com/google-jobs-api](https://serpapi.com/google-jobs-api)
@@ -400,16 +402,4 @@ MIT License.
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub. Once dependencies are installed, you can run the tests with `pytest`.
-
-## Publishing a new release
-
-1. Update the version in `serpapi/__version__.py`.
-2. Push a tag — the release pipeline runs automatically:
-   ```sh
-   git tag v1.2.3
-   git push origin v1.2.3
-   ```
-   This triggers the [release workflow](.github/workflows/release.yml), which tests, builds, and publishes to PyPI, then smoke-tests the published package.
-
-> **Required secret:** `API_KEY` (used in smoke-test live search).
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, testing, and publishing instructions.

serpapi-1.1.2/assets/serpapi-logo.svg

@@ -0,0 +1,15 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 420 96" role="img" aria-label="SerpApi">
+  <defs>
+    <linearGradient id="serpapi-logo-gradient" x1="12" y1="84" x2="84" y2="12" gradientUnits="userSpaceOnUse">
+      <stop offset="0" stop-color="#377FEA"/>
+      <stop offset="1" stop-color="#6937EA"/>
+    </linearGradient>
+  </defs>
+  <rect x="0" y="0" width="96" height="96" rx="22" fill="url(#serpapi-logo-gradient)"/>
+  <path d="M30 0v31M0 65h30v31M66 31h30M66 31v34M66 65v31" fill="none" stroke="#fff" stroke-width="10" stroke-linecap="round"/>
+  <circle cx="30" cy="31" r="12" fill="#fff"/>
+  <circle cx="30" cy="65" r="12" fill="#fff"/>
+  <circle cx="66" cy="31" r="12" fill="#fff"/>
+  <circle cx="66" cy="65" r="12" fill="#fff"/>
+  <text x="122" y="62" fill="#ffffff" font-family="Lato, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif" font-size="43" font-weight="700" letter-spacing="0">SerpApi</text>
+</svg>

serpapi-1.1.2/docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

serpapi-1.1.2/docs/_static/custom.css

@@ -0,0 +1,99 @@
+/* Official palette: https://serpapi.com/media */
+:root {
+    --serpapi-blue: #377fea;
+    --serpapi-purple: #6937ea;
+    --serpapi-dark: #313131;
+    --serpapi-gradient: linear-gradient(47deg, #377fea, #6937ea);
+    --sd-color-primary: var(--serpapi-purple);
+    --sd-color-primary-highlight: var(--serpapi-purple);
+    --sd-color-primary-text: #ffffff;
+    --sd-color-secondary: var(--serpapi-blue);
+    --sd-color-tabs-label-active: var(--serpapi-purple);
+    --sd-color-tabs-label-hover: var(--serpapi-purple);
+    --sd-color-tabs-underline-active: var(--serpapi-blue);
+    --sd-color-tabs-underline-hover: var(--serpapi-blue);
+}
+
+.wy-side-nav-search > a img.logo {
+    width: 210px;
+    height: auto;
+}
+
+.wy-side-nav-search,
+.wy-nav-top {
+    background-color: #2b2145;
+    color: #ffffff;
+    border-bottom: 4px solid var(--serpapi-blue);
+    border-image: var(--serpapi-gradient) 1;
+}
+
+.wy-nav-top a {
+    color: #ffffff;
+}
+
+.wy-side-nav-search input[type="text"] {
+    border-color: var(--serpapi-blue);
+}
+
+.wy-nav-side {
+    background: var(--serpapi-dark);
+}
+
+.wy-menu-vertical header,
+.wy-menu-vertical p.caption {
+    color: #ffffff;
+    height: auto;
+    min-height: 32px;
+    line-height: 1.5;
+    padding-top: 0.4em;
+    padding-bottom: 0.4em;
+    white-space: normal;
+}
+
+.wy-menu-vertical a:hover {
+    background-color: var(--serpapi-purple);
+    color: #ffffff;
+}
+
+.wy-menu-vertical > ul + ul {
+    margin-top: 12px;
+}
+
+.wy-menu-vertical > ul + ul > li > a {
+    font-weight: 700;
+}
+
+.wy-menu-vertical li.current > a,
+.wy-menu-vertical li.current > a:hover {
+    color: var(--serpapi-purple);
+    box-shadow: inset 4px 0 var(--serpapi-blue);
+}
+
+.wy-nav-content {
+    color: var(--serpapi-dark);
+}
+
+/* Purple stays readable for small text on the light content background. */
+.wy-nav-content a:not(.btn),
+.wy-nav-content a:not(.btn):visited,
+.rst-content code.literal,
+.rst-content a code {
+    color: var(--serpapi-purple);
+}
+
+.wy-nav-content a:not(.btn):hover {
+    text-decoration: underline;
+}
+
+html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) > dt {
+    color: var(--serpapi-purple);
+    background: rgba(105, 55, 234, 0.06);
+    border-top-color: var(--serpapi-blue);
+}
+
+.wy-nav-content a:focus-visible,
+.wy-menu-vertical a:focus-visible,
+.wy-side-nav-search input[type="text"]:focus-visible {
+    outline: 2px solid var(--serpapi-blue);
+    outline-offset: 2px;
+}

serpapi-1.1.2/docs/ai-agents.md

@@ -0,0 +1,33 @@
+---
+title: "AI Agents"
+description: "Use SerpApi search tools, Markdown results, and API references in AI agents."
+---
+
+# AI Agents
+
+An AI agent can call SerpApi to search the web and use the returned text and links when answering a question.
+
+## SerpApi Search Tools
+
+If you use a Python agent SDK, we recommend [SerpApi Search Tools](https://github.com/serpapi/serpapi-search-tools-python). It is a separate package for plugging SerpApi search tools into your agents.
+
+## Request Markdown Results
+
+To write your own search tool with `serpapi.Client`, pass `output="md"`. Markdown is plain text with formatting for headings, links, and tables.
+
+Set your API key as described in [Getting Started](user_guide/getting-started.md#installation), then run:
+
+```python
+import os
+import serpapi
+
+client = serpapi.Client(api_key=os.environ["SERPAPI_KEY"])
+markdown = client.search(engine="google", q="Python release news", output="md")
+print(markdown[:500])
+```
+
+The example prints the first 500 characters. Pass the full `markdown` string back to your agent as the search tool's result. See [Output Formats](user_guide/output-formats.md) for JSON, Markdown, and HTML examples and the Python values they return.
+
+## API Parameter Reference
+
+Give your coding agent [SerpApi's `llms.txt`](https://serpapi.com/llms.txt) when asking it to write search code. This file lists the Markdown documentation for each API. Ask the agent to read the relevant API page for required parameters, optional filters, and response fields.