Merge remote-tracking branch 'origin/master' into feat/docs-enhancements

Author: adarshdigievo

.github/workflows/ci.yml

@@ -15,7 +15,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12", "3.13"]
+        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12", "3.13", "3.14"]
 
     steps:
     - name: Checkout repository
@@ -36,7 +36,7 @@ jobs:
         API_KEY: ${{ secrets.API_KEY }}
 
     - name: Run example tests
-      if: matrix.python-version == '3.13'
+      if: matrix.python-version == '3.14'
       run: pytest -k "example"
       env:
         API_KEY: ${{ secrets.API_KEY }}

.github/workflows/release.yml

@@ -3,6 +3,12 @@ name: Release
 on:
   push:
     tags: ['v**']
+  workflow_dispatch:
+    inputs:
+      allow_example_test_failures:
+        description: 'Publish even if the live example tests fail (use only when a SerpApi engine is down)'
+        type: boolean
+        default: false
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
@@ -14,10 +20,16 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12", "3.13"]
+        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12", "3.13", "3.14"]
     steps:
       - uses: actions/checkout@v6
 
+      - name: Ensure ref is a tag
+        if: github.ref_type != 'tag'
+        run: |
+          echo "Release must run against a tag, got '${{ github.ref }}'" >&2
+          exit 1
+
       - uses: actions/setup-python@v6
         with:
           python-version: ${{ matrix.python-version }}
@@ -31,7 +43,8 @@ jobs:
           API_KEY: ${{ secrets.API_KEY }}
 
       - name: Run example tests
-        if: matrix.python-version == '3.13'
+        if: matrix.python-version == '3.14'
+        continue-on-error: ${{ inputs.allow_example_test_failures == true }}
         run: pytest -k "example"
         env:
           API_KEY: ${{ secrets.API_KEY }}
@@ -62,19 +75,18 @@ jobs:
     name: Publish release
     needs: [build]
     runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/serpapi
     permissions:
       contents: write
-      packages: write
+      id-token: write
     steps:
       - uses: actions/download-artifact@v8
         with:
           name: dist
           path: dist/
 
-      - uses: actions/setup-python@v6
-        with:
-          python-version: "3.13"
-
       - name: Create GitHub Release
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
@@ -83,14 +95,8 @@ jobs:
           gh release create ${{ github.ref_name }} dist/* --generate-notes \
             || gh release upload ${{ github.ref_name }} dist/* --clobber
 
-      - name: Install twine
-        run: pip install --upgrade pip twine
-
       - name: Publish to PyPI
-        env:
-          TWINE_USERNAME: __token__
-          TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
-        run: twine upload dist/*
+        uses: pypa/gh-action-pypi-publish@release/v1
 
   smoke-test:
     name: Smoke test published package

HISTORY.md

@@ -1,6 +1,14 @@
 Release History
 ===============
 
+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)
 ------------------
 

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
@@ -277,6 +293,38 @@ results = client.search({
 ```
 - API Documentation: [serpapi.com/google-reverse-image](https://serpapi.com/google-reverse-image)
 
+### Search Google Lens by image URL or upload
+
+Google Lens accepts either a publicly accessible image URL or an uploaded
+image. To search by URL, pass the URL directly:
+
+```python
+import os
+import serpapi
+
+client = serpapi.Client(api_key=os.getenv("SERPAPI_KEY"))
+results = client.search({
+    "engine": "google_lens",
+    "url": "https://i.imgur.com/HBrB8p0.png",
+})
+```
+
+To search a local image, upload it first and pass its temporary `image_id` to
+Google Lens:
+
+```python
+upload = client.upload_image("/path/to/image.png")
+results = client.search({
+    "engine": "google_lens",
+    "image_id": upload["image_id"],
+})
+```
+
+Uploaded images can be JPG/JPEG, PNG, or WebP files up to 500 KB. The returned
+`image_id` expires after 10 minutes.
+
+- 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
@@ -380,4 +428,4 @@ Bug reports and pull requests are welcome on GitHub. Once dependencies are insta
    ```
    This triggers the [release workflow](.github/workflows/release.yml), which tests, builds, and publishes to PyPI, then smoke-tests the published package.
 
-> **Required secrets:** `PYPI_API_TOKEN` (PyPI upload token) and `API_KEY` (used in smoke-test live search).
+> **Required secret:** `API_KEY` (used in smoke-test live search).

docs/index.rst

@@ -0,0 +1,193 @@
+.. 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 <https://serpapi.com>`_.
+
+--------------
+
+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 <serpapi.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 <https://serpapi.com/search-api>`_ 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.upload_image
+.. autofunction:: serpapi.locations
+.. autofunction:: serpapi.account
+
+
+
+Results from SerpApi.com
+------------------------
+
+When a successful search has been executed, the method returns
+a :class:`SerpResults <serpapi.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)
+   <class 'serpapi.models.SerpResults'>
+
+   >>> 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())
+   <class 'dict'>
+
+You can get the next page of results::
+
+   >>> type(s.next_page())
+   <class 'serpapi.models.SerpResults'>
+
+To iterate over all pages of results, it's recommended to :ref:`use the API Client directly <using-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.upload_image
+   .. 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`

pyproject.toml

@@ -28,6 +28,7 @@ classifiers = [
   "Programming Language :: Python :: 3.11",
   "Programming Language :: Python :: 3.12",
   "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
   "Programming Language :: Python :: Implementation :: CPython",
   "Natural Language :: English",
   "Topic :: Utilities",

serpapi/__version__.py

@@ -1 +1 @@
-__version__ = "1.0.2"
+__version__ = "1.1.0"