serpapi 1.0.2__tar.gz → 1.1.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: serpapi
-Version: 1.0.2
+Version: 1.1.0
 Summary: The official Python client for SerpApi.com.
 Author-email: SerpApi <support@serpapi.com>
 License: MIT
@@ -18,6 +18,7 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Programming Language :: Python :: Implementation :: CPython
 Classifier: Natural Language :: English
 Classifier: Topic :: Utilities
@@ -313,6 +314,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
@@ -416,4 +449,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).

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

@@ -277,6 +277,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 +412,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).

{serpapi-1.0.2 → serpapi-1.1.0}/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-1.1.0/serpapi/__version__.py

@@ -0,0 +1 @@
+__version__ = "1.1.0"

{serpapi-1.0.2 → serpapi-1.1.0}/serpapi/core.py

@@ -1,3 +1,6 @@
+import io
+import os
+
 from .http import HTTPClient
 from .exceptions import SearchIDNotProvided
 from .models import SerpResults
@@ -108,6 +111,53 @@ class Client(HTTPClient):
         r = self.request("GET", f"/searches/{ search_id }", params=params, **request_kwargs)
         return SerpResults.from_http_response(r, client=self)
 
+    def upload_image(self, image, **kwargs):
+        """Upload an image to SerpApi's Image API.
+
+        ``image`` can be a filesystem path or an open binary file object. The
+        returned dictionary contains an ``image_id`` that can be passed to
+        :meth:`search` for engines that accept uploaded images, such as Google
+        Lens.
+
+        :param image: a path or open binary file object containing a JPG/JPEG,
+            PNG, or WebP image no larger than 500 KB.
+        :param api_key: the API Key to use for SerpApi.com.
+        :param **: any additional multipart form fields to pass to the API.
+
+        **Learn more**: https://serpapi.com/image-api
+        """
+        request_kwargs = {}
+        for key in ["timeout", "proxies", "verify", "stream", "cert"]:
+            if key in kwargs:
+                request_kwargs[key] = kwargs.pop(key)
+
+        data = kwargs
+        if "api_key" not in data:
+            data["api_key"] = self.api_key
+
+        image_file = None
+        try:
+            if isinstance(image, (str, os.PathLike)):
+                image_file = open(image, "rb")
+                image = image_file
+            elif isinstance(image, io.TextIOBase):
+                raise TypeError(
+                    "image file must be opened in binary mode, e.g. open(path, 'rb')"
+                )
+
+            r = self.request(
+                "POST",
+                "/image",
+                params={},
+                data=data,
+                files={"image": image},
+                **request_kwargs,
+            )
+            return r.json()
+        finally:
+            if image_file is not None:
+                image_file.close()
+
     def locations(self, params: dict = None, **kwargs):
         """Get a list of supported Google locations.
 
@@ -168,5 +218,6 @@ class Client(HTTPClient):
 _client = Client()
 search = _client.search
 search_archive = _client.search_archive
+upload_image = _client.upload_image
 locations = _client.locations
 account = _client.account

{serpapi-1.0.2 → serpapi-1.1.0}/serpapi/http.py

@@ -23,7 +23,9 @@ class HTTPClient:
 
     def request(self, method, path, params, *, assert_200=True, **kwargs):
         # Inject the API Key into the params.
-        if "api_key" not in params:
+        request_data = kwargs.get("data")
+        api_key_in_data = isinstance(request_data, dict) and "api_key" in request_data
+        if "api_key" not in params and not api_key_in_data:
             params["api_key"] = self.api_key
 
         # Build the URL, as needed.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: serpapi
-Version: 1.0.2
+Version: 1.1.0
 Summary: The official Python client for SerpApi.com.
 Author-email: SerpApi <support@serpapi.com>
 License: MIT
@@ -18,6 +18,7 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Programming Language :: Python :: Implementation :: CPython
 Classifier: Natural Language :: English
 Classifier: Topic :: Utilities
@@ -313,6 +314,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
@@ -416,4 +449,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).

{serpapi-1.0.2 → serpapi-1.1.0}/serpapi.egg-info/SOURCES.txt

@@ -28,6 +28,7 @@ tests/example_search_google_autocomplete_test.py
 tests/example_search_google_events_test.py
 tests/example_search_google_images_test.py
 tests/example_search_google_jobs_test.py
+tests/example_search_google_light_test.py
 tests/example_search_google_local_services_test.py
 tests/example_search_google_maps_test.py
 tests/example_search_google_play_test.py
@@ -39,5 +40,6 @@ tests/example_search_walmart_test.py
 tests/example_search_yahoo_test.py
 tests/example_search_youtube_test.py
 tests/test_exceptions.py
+tests/test_image_upload.py
 tests/test_integration.py
 tests/test_timeout.py

serpapi-1.1.0/tests/example_search_google_light_test.py

@@ -0,0 +1,12 @@
+# Example: google_light search engine
+import pytest
+import os
+import serpapi
+
+def test_search_google_light(client):
+  data = client.search({
+      'engine': 'google_light',
+      'q': 'coffee',
+  })
+  assert data.get('error') is None
+  assert data['organic_results']

serpapi-1.1.0/tests/test_image_upload.py

@@ -0,0 +1,101 @@
+from io import BytesIO, StringIO
+from unittest.mock import Mock
+
+import pytest
+import requests
+
+import serpapi
+
+
+def json_response(data):
+    response = requests.Response()
+    response.status_code = 200
+    response._content = data
+    return response
+
+
+def test_upload_image_path_sends_multipart_request(tmp_path):
+    image_path = tmp_path / "test.png"
+    image_path.write_bytes(b"fake-png-data")
+    client = serpapi.Client(api_key="test-api-key")
+
+    def request(**kwargs):
+        assert kwargs["method"] == "POST"
+        assert kwargs["url"] == "https://serpapi.com/image"
+        assert kwargs["params"] == {}
+        assert kwargs["data"] == {"api_key": "test-api-key"}
+        assert kwargs["files"]["image"].name == str(image_path)
+        assert kwargs["files"]["image"].read() == b"fake-png-data"
+        return json_response(
+            b'{"message": "Image uploaded successfully.", "image_id": "image-123"}'
+        )
+
+    client.session.request = Mock(side_effect=request)
+
+    result = client.upload_image(image_path)
+
+    assert result["image_id"] == "image-123"
+
+
+def test_upload_image_accepts_open_binary_file_and_request_options():
+    image = BytesIO(b"fake-image-data")
+    client = serpapi.Client(api_key="client-api-key", timeout=10)
+    client.session.request = Mock(
+        return_value=json_response(b'{"image_id": "image-456"}')
+    )
+
+    result = client.upload_image(
+        image,
+        api_key="request-api-key",
+        timeout=5,
+        zero_trace="true",
+    )
+
+    assert result == {"image_id": "image-456"}
+    assert not image.closed
+    _, request_kwargs = client.session.request.call_args
+    assert request_kwargs["params"] == {}
+    assert request_kwargs["data"] == {
+        "api_key": "request-api-key",
+        "zero_trace": "true",
+    }
+    assert request_kwargs["files"] == {"image": image}
+    assert request_kwargs["timeout"] == 5
+
+
+def test_upload_image_rejects_text_mode_file(tmp_path):
+    image_path = tmp_path / "test.png"
+    image_path.write_text("not binary image data")
+    client = serpapi.Client(api_key="test-api-key")
+    client.session.request = Mock()
+
+    with image_path.open("r") as image:
+        with pytest.raises(TypeError, match="opened in binary mode"):
+            client.upload_image(image)
+
+    client.session.request.assert_not_called()
+
+
+def test_upload_image_rejects_string_io():
+    client = serpapi.Client(api_key="test-api-key")
+    client.session.request = Mock()
+
+    with pytest.raises(TypeError, match="opened in binary mode"):
+        client.upload_image(StringIO("not binary image data"))
+
+    client.session.request.assert_not_called()
+
+
+def test_request_injects_api_key_when_form_data_does_not_include_it():
+    client = serpapi.Client(api_key="test-api-key")
+    client.session.request = Mock(return_value=json_response(b"{}"))
+
+    client.request("POST", "/example", params={}, data={"field": "value"})
+
+    _, request_kwargs = client.session.request.call_args
+    assert request_kwargs["params"] == {"api_key": "test-api-key"}
+    assert request_kwargs["data"] == {"field": "value"}
+
+
+def test_module_exposes_upload_image_entrypoint():
+    assert callable(serpapi.upload_image)

serpapi-1.1.0/tests/test_integration.py

@@ -0,0 +1,163 @@
+from urllib.parse import parse_qs, urlparse
+
+import pytest
+
+import serpapi
+
+
+def _query_param(url, param):
+    values = parse_qs(urlparse(url).query).get(param)
+    if values:
+        return values[0]
+
+
+def test_basic_import():
+    """Test that basic import works as intended."""
+    import serpapi
+
+
+def test_entrypoints(client):
+    """Test that pure references to the publicly accessible API surface introduces no errors."""
+
+    for api in [client, serpapi]:
+        assert api.account
+        assert api.search
+        assert api.search_archive
+        assert api.locations
+
+
+def test_locations_query_limit_and_shape(client):
+    locations = client.locations(q="Austin", limit=5)
+
+    assert isinstance(locations, list)
+    assert 0 < len(locations) <= 5
+
+    expected_fields = {
+        "id",
+        "name",
+        "canonical_name",
+        "country_code",
+        "target_type",
+        "reach",
+    }
+
+    for location in locations:
+        assert expected_fields.issubset(location.keys())
+        assert isinstance(location["canonical_name"], str)
+
+    assert any(
+        "Austin" in location["name"] or "Austin" in location["canonical_name"]
+        for location in locations
+    )
+
+
+def test_search_accepts_location_from_locations_api(client):
+    locations = client.locations(q="Austin", limit=1)
+    location_name = locations[0]["canonical_name"]
+
+    search = client.search(q="coffee", location=location_name)
+
+    assert search.get("error") is None
+    assert search["organic_results"]
+    assert "Austin" in search["search_parameters"]["location_requested"]
+    assert "United States" in search["search_parameters"]["location_used"]
+
+
+def test_account_without_credentials():
+    """Ensure that an HTTPError is raised when account is accessed without API Credentials."""
+    with pytest.raises(serpapi.HTTPError):
+        serpapi.account()
+
+
+def test_account_with_bad_credentials(invalid_key_client):
+    """Ensure that an HTTPError is raised when account is accessed with invalid API Credentials."""
+    with pytest.raises(serpapi.HTTPError) as exc_info:
+        invalid_key_client.account()
+        
+    assert exc_info.value.response.status_code == 401
+
+
+def test_account_with_credentials(client):
+    """Ensure that account appears to be returning valid data if the API Key is correct."""
+    account = client.account()
+    assert account
+    assert account.keys()
+    assert isinstance(account, dict)
+
+
+def test_search_with_missing_params(client):
+    with pytest.raises(serpapi.HTTPError) as exc_info:
+        client.search({ "q": "" })
+        
+    assert exc_info.value.status_code == 400
+    assert "Missing query `q` parameter" in exc_info.value.error
+
+
+def test_coffee_search(coffee_search):
+    assert isinstance(coffee_search, serpapi.SerpResults)
+    assert hasattr(coffee_search, "__getitem__")
+
+
+def test_coffee_search_as_dict(coffee_search):
+    d = coffee_search.as_dict()
+    assert isinstance(d, dict)
+
+
+def test_search_output_html_contains_raw_html_document(coffee_search_html):
+    assert isinstance(coffee_search_html, str)
+    assert "<html" in coffee_search_html.lower()
+    assert "</html>" in coffee_search_html.lower()
+    assert "coffee" in coffee_search_html.lower()
+    assert not hasattr(coffee_search_html, "next_page_url")
+
+
+def test_next_page_url_uses_serpapi_pagination_next(coffee_search):
+    next_page_url = coffee_search.next_page_url
+
+    assert next_page_url == coffee_search["serpapi_pagination"]["next"]
+    assert _query_param(next_page_url, "start") == "10"
+    assert _query_param(next_page_url, "api_key") is None
+
+
+def test_yield_pages_returns_unique_search_pages(coffee_search):
+    max_pages = 3
+    pages = list(coffee_search.yield_pages(max_pages=max_pages))
+
+    assert len(pages) == max_pages
+    assert len({page["search_metadata"]["id"] for page in pages}) == max_pages
+    assert "start" not in pages[0]["search_parameters"]
+    assert int(pages[1]["search_parameters"]["start"]) == 10
+    assert int(pages[2]["search_parameters"]["start"]) == 20
+
+
+def test_next_page_advances_start_and_returns_new_results(coffee_search):
+    next_page = coffee_search.next_page()
+
+    assert isinstance(next_page, serpapi.SerpResults)
+    assert coffee_search["search_metadata"]["id"] != next_page["search_metadata"]["id"]
+    assert int(next_page["search_parameters"]["start"]) == 10
+    assert next_page["organic_results"]
+
+    page_number = next_page["search_information"].get("page_number")
+    if page_number is not None:
+        assert int(page_number) == 2
+
+
+def test_search_archive_round_trips_search_id(client, coffee_search):
+    search_id = coffee_search["search_metadata"]["id"]
+
+    archived_search = client.search_archive(search_id=search_id)
+
+    assert isinstance(archived_search, serpapi.SerpResults)
+    assert archived_search["search_metadata"]["id"] == search_id
+
+
+def test_search_function_signature(coffee_params, client):
+    s = client.search(coffee_params)
+    assert s["search_metadata"]["id"]
+
+    s = client.search(**coffee_params)
+    assert s["search_metadata"]["id"]
+
+    s = client.search(q='coffee')
+    assert s["search_metadata"]["id"]

serpapi-1.0.2/serpapi/__version__.py

@@ -1 +0,0 @@
-__version__ = "1.0.2"

serpapi-1.0.2/tests/test_integration.py

@@ -1,94 +0,0 @@
-import pytest
-
-import serpapi
-
-
-def test_basic_import():
-    """Test that basic import works as intended."""
-    import serpapi
-
-
-def test_entrypoints(client):
-    """Test that pure references to the publicly accessible API surface introduces no errors."""
-
-    for api in [client, serpapi]:
-        assert api.account
-        assert api.search
-        assert api.search_archive
-        assert api.locations
-
-
-def test_account_without_credentials():
-    """Ensure that an HTTPError is raised when account is accessed without API Credentials."""
-    with pytest.raises(serpapi.HTTPError):
-        serpapi.account()
-
-
-def test_account_with_bad_credentials(invalid_key_client):
-    """Ensure that an HTTPError is raised when account is accessed with invalid API Credentials."""
-    with pytest.raises(serpapi.HTTPError) as exc_info:
-        invalid_key_client.account()
-        
-    assert exc_info.value.response.status_code == 401
-
-
-def test_account_with_credentials(client):
-    """Ensure that account appears to be returning valid data if the API Key is correct."""
-    account = client.account()
-    assert account
-    assert account.keys()
-    assert isinstance(account, dict)
-
-
-def test_search_with_missing_params(client):
-    with pytest.raises(serpapi.HTTPError) as exc_info:
-        client.search({ "q": "" })
-        
-    assert exc_info.value.status_code == 400
-    assert "Missing query `q` parameter" in exc_info.value.error
-
-
-def test_coffee_search(coffee_search):
-    assert isinstance(coffee_search, serpapi.SerpResults)
-    assert hasattr(coffee_search, "__getitem__")
-
-
-def test_coffee_search_as_dict(coffee_search):
-    d = coffee_search.as_dict()
-    assert isinstance(d, dict)
-
-
-def test_coffee_search_html(coffee_search_html):
-    assert isinstance(coffee_search_html, str)
-    assert not hasattr(coffee_search_html, "next_page_url")
-
-
-def test_coffee_search_n_pages(coffee_search):
-    page_count = 0
-    max_pages = 3
-
-    for page in coffee_search.yield_pages(max_pages=max_pages):
-        if page_count == 0:
-            assert 'start' not in page['search_parameters'], "The 'start' parameter should not be in the first page"
-        
-        page_count += 1
-
-    assert page_count == max_pages
-
-
-def test_coffee_search_next_page(coffee_search):
-    next_page = coffee_search.next_page()
-
-    assert isinstance(next_page, serpapi.SerpResults)
-    assert coffee_search["search_metadata"]["id"] != next_page["search_metadata"]["id"]
-
-
-def test_search_function_signature(coffee_params, client):
-    s = client.search(coffee_params)
-    assert s["search_metadata"]["id"]
-
-    s = client.search(**coffee_params)
-    assert s["search_metadata"]["id"]
-
-    s = client.search(q='coffee')
-    assert s["search_metadata"]["id"]