serpbit 0.1.0__py3-none-any.whl

serpbit/__init__.py

@@ -0,0 +1,26 @@
+"""Serpbit: Google results as data. A small client for https://api.serpbit.com, on the standard library alone."""
+
+from ._client import VERSION as __version__
+from ._client import Serpbit
+from ._webhook import verify_webhook
+from ._errors import (
+    APIConnectionError,
+    APIError,
+    AuthenticationError,
+    BadRequestError,
+    InsufficientCreditsError,
+    RateLimitError,
+    SerpbitError,
+)
+
+__all__ = [
+    "Serpbit",
+    "verify_webhook",
+    "SerpbitError",
+    "APIConnectionError",
+    "APIError",
+    "AuthenticationError",
+    "BadRequestError",
+    "InsufficientCreditsError",
+    "RateLimitError",
+]

serpbit/_client.py

@@ -0,0 +1,201 @@
+"""The client: one method per API door, each a GET whose keyword arguments are the door's parameters."""
+
+import json
+import os
+import random
+import socket
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+import uuid
+from typing import Any, Dict, List, Optional, Union
+
+from ._errors import APIConnectionError, SerpbitError, error_for
+
+DEFAULT_BASE_URL = "https://api.serpbit.com"
+VERSION = "0.1.0"
+
+# A call is retried on these: the rate limit (after Retry-After), Google giving no page in time, our side failing.
+_RETRY = {429, 500, 502, 503, 504}
+
+Answer = Union[Dict[str, Any], str]
+
+
+class Serpbit:
+    """A Serpbit client.
+
+    >>> from serpbit import Serpbit
+    >>> sb = Serpbit()  # the key from SERPBIT_API_KEY
+    >>> answer = sb.search("espresso grinder", gl="de", pages=2, content=3)
+    >>> answer["organic"][0]["title"]
+
+    Every method returns the API's JSON as a dict, or Markdown as a str with output="md". A failed call raises a
+    SerpbitError. A retried call carries one Idempotency-Key, so a call that was answered but whose answer was lost
+    on the way is given back free rather than asked and billed again.
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: Optional[str] = None,
+        timeout: float = 90.0,
+        max_retries: int = 2,
+    ) -> None:
+        self.api_key = api_key or os.environ.get("SERPBIT_API_KEY", "")
+        if not self.api_key:
+            raise SerpbitError("no API key: pass api_key or set SERPBIT_API_KEY (keys are made at https://app.serpbit.com/keys)")
+        self.base_url = (base_url or os.environ.get("SERPBIT_BASE_URL") or DEFAULT_BASE_URL).rstrip("/")
+        self.timeout = timeout
+        self.max_retries = max(0, max_retries)
+        # The last answer's id and credits, from its headers: a Markdown answer has no JSON to carry them.
+        self.last_request_id: Optional[str] = None
+        self.last_credits: Optional[int] = None
+
+    # --- the doors -------------------------------------------------------------------------------------------------
+
+    def search(self, q: Optional[str] = None, **params: Any) -> Answer:
+        """Google's results page (/v1/search). url= takes a Google results address instead of q."""
+        return self.request("/v1/search", q=q, **params)
+
+    def news(self, q: str, **params: Any) -> Answer:
+        """Google's News tab (/v1/news)."""
+        return self.request("/v1/news", q=q, **params)
+
+    def shopping(self, q: str, **params: Any) -> Answer:
+        """Google's Shopping tab (/v1/shopping)."""
+        return self.request("/v1/shopping", q=q, **params)
+
+    def shopping_product(self, product_id: Optional[str] = None, **params: Any) -> Answer:
+        """One product and every store's offer (/v1/shopping/product)."""
+        return self.request("/v1/shopping/product", product_id=product_id, **params)
+
+    def images(self, q: str, **params: Any) -> Answer:
+        """Google's Images tab (/v1/images)."""
+        return self.request("/v1/images", q=q, **params)
+
+    def videos(self, q: str, **params: Any) -> Answer:
+        """Google's Videos tab (/v1/videos)."""
+        return self.request("/v1/videos", q=q, **params)
+
+    def maps(self, q: str, **params: Any) -> Answer:
+        """Places as Google Maps lists them (/v1/maps)."""
+        return self.request("/v1/maps", q=q, **params)
+
+    def autocomplete(self, q: str, **params: Any) -> Answer:
+        """Google's search-box suggestions (/v1/autocomplete)."""
+        return self.request("/v1/autocomplete", q=q, **params)
+
+    def ai_mode(self, q: str, **params: Any) -> Answer:
+        """Google's AI Mode answer with its sources (/v1/ai-mode)."""
+        return self.request("/v1/ai-mode", q=q, **params)
+
+    # --- batches ---------------------------------------------------------------------------------------------------
+
+    def batch(self, requests: List[Dict[str, Any]], *, webhook: Optional[str] = None,
+              idempotency_key: Optional[str] = None) -> Dict[str, Any]:
+        """Start a batch of up to 1,000 calls (POST /v1/batches), each {"path": "/v1/search", "params": {...}, "id": ...}.
+
+        The calls run in the background at the key's limits; each answer goes to webhook as it comes (verify it with
+        serpbit.verify_webhook) and stays readable with batch_results for a day after the batch ends.
+        """
+        body: Dict[str, Any] = {"requests": [
+            {**r, "params": {k: v for k, v in (r.get("params") or {}).items() if v is not None and v is not False}}
+            for r in requests]}
+        if webhook:
+            body["webhook"] = webhook
+        return self.request("/v1/batches", method="POST", json_body=body, idempotency_key=idempotency_key)
+
+    def get_batch(self, batch_id: str) -> Dict[str, Any]:
+        """A batch's state and each call's status (GET /v1/batches/{id})."""
+        return self.request("/v1/batches/" + urllib.parse.quote(batch_id, safe=""))
+
+    def batch_results(self, batch_id: str, *, offset: int = 0, limit: int = 100) -> Dict[str, Any]:
+        """A batch's answers, limit (at most 100) from offset (GET /v1/batches/{id}/results)."""
+        return self.request("/v1/batches/" + urllib.parse.quote(batch_id, safe="") + "/results", offset=offset, limit=limit)
+
+    # --- the call --------------------------------------------------------------------------------------------------
+
+    def request(self, path: str, *, method: str = "GET", json_body: Any = None, idempotency_key: Optional[str] = None,
+                **params: Any) -> Answer:
+        """Call path with params. True is sent as true; None and False are left out; a list is joined by commas."""
+        query = {k: _value(v) for k, v in params.items() if v is not None and v is not False}
+        url = self.base_url + path + ("?" + urllib.parse.urlencode(query) if query else "")
+        key = idempotency_key or (uuid.uuid4().hex if self.max_retries else None)
+        headers = {
+            "Authorization": "Bearer " + self.api_key,
+            "Accept": "application/json, text/markdown",
+            "User-Agent": "serpbit-python/" + VERSION,
+        }
+        if key:
+            headers["Idempotency-Key"] = key
+        data = None
+        if json_body is not None:
+            data = json.dumps(json_body).encode()
+            headers["Content-Type"] = "application/json"
+        attempt = 0
+        while True:
+            try:
+                req = urllib.request.Request(url, data=data, headers=headers, method=method)
+                with urllib.request.urlopen(req, timeout=self.timeout) as resp:
+                    body = resp.read()
+                    self.last_request_id = resp.headers.get("X-Request-Id")
+                    self.last_credits = _int(resp.headers.get("X-Credits"))
+                    if resp.headers.get_content_type() == "application/json":
+                        return json.loads(body)
+                    return body.decode("utf-8")
+            except urllib.error.HTTPError as e:
+                body = e.read()
+                retry_after = _float(e.headers.get("Retry-After"))
+                if e.code in _RETRY and attempt < self.max_retries:
+                    time.sleep(_backoff(attempt, retry_after))
+                    attempt += 1
+                    continue
+                raise _refusal(e.code, body, e.headers.get("X-Request-Id"), retry_after) from None
+            except (urllib.error.URLError, socket.timeout, TimeoutError, ConnectionError) as e:
+                if attempt < self.max_retries:
+                    time.sleep(_backoff(attempt, None))
+                    attempt += 1
+                    continue
+                raise APIConnectionError(f"could not reach {self.base_url}: {getattr(e, 'reason', e)}") from None
+
+
+def _value(v: Any) -> str:
+    if v is True:
+        return "true"
+    if isinstance(v, (list, tuple)):
+        return ",".join(str(x) for x in v)
+    return str(v)
+
+
+def _int(s: Optional[str]) -> Optional[int]:
+    try:
+        return int(s) if s is not None else None
+    except ValueError:
+        return None
+
+
+def _float(s: Optional[str]) -> Optional[float]:
+    try:
+        return float(s) if s is not None else None
+    except ValueError:
+        return None
+
+
+def _backoff(attempt: int, retry_after: Optional[float]) -> float:
+    if retry_after is not None:
+        return min(retry_after, 60.0)
+    return min(0.5 * 2**attempt, 8.0) * (0.75 + random.random() / 2)
+
+
+def _refusal(status: int, body: bytes, request_id: Optional[str], retry_after: Optional[float]) -> SerpbitError:
+    try:
+        data = json.loads(body)
+    except ValueError:
+        data = {}
+    if not isinstance(data, dict):
+        data = {}
+    message = data.get("message") or f"the API answered {status}"
+    return error_for(status, message, code=data.get("error"), request_id=data.get("request_id") or request_id,
+                     body=data, retry_after=retry_after)

serpbit/_errors.py

@@ -0,0 +1,75 @@
+"""Errors, one class a kind of refusal: catch SerpbitError for all of them."""
+
+from typing import Any, Mapping, Optional
+
+
+class SerpbitError(Exception):
+    """A call that did not answer. status, code and request_id are the API's (request_id is what support asks for)."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status: Optional[int] = None,
+        code: Optional[str] = None,
+        request_id: Optional[str] = None,
+        body: Optional[Mapping[str, Any]] = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status = status
+        self.code = code
+        self.request_id = request_id
+        self.body = body
+
+    def __str__(self) -> str:
+        parts = [self.message]
+        if self.status:
+            parts.append(f"status {self.status}")
+        if self.code:
+            parts.append(self.code)
+        if self.request_id:
+            parts.append(f"request_id {self.request_id}")
+        return " · ".join(parts)
+
+
+class BadRequestError(SerpbitError):
+    """400: a parameter the API does not take, or a value out of its range."""
+
+
+class AuthenticationError(SerpbitError):
+    """401: no key, or a key that is revoked or unknown."""
+
+
+class InsufficientCreditsError(SerpbitError):
+    """402: the account has not the credits this call needs."""
+
+
+class RateLimitError(SerpbitError):
+    """429: over the key's requests a minute or at once. retry_after is the seconds the API asked to wait."""
+
+    def __init__(self, message: str, *, retry_after: Optional[float] = None, **kw: Any) -> None:
+        super().__init__(message, **kw)
+        self.retry_after = retry_after
+
+
+class APIError(SerpbitError):
+    """5xx: Google gave no page within the call's attempts and time (503), or something failed on our side."""
+
+
+class APIConnectionError(SerpbitError):
+    """The API could not be reached, or did not answer in time."""
+
+
+def error_for(status: int, message: str, retry_after: Optional[float] = None, **kw: Any) -> SerpbitError:
+    if status == 400:
+        return BadRequestError(message, status=status, **kw)
+    if status == 401:
+        return AuthenticationError(message, status=status, **kw)
+    if status == 402:
+        return InsufficientCreditsError(message, status=status, **kw)
+    if status == 429:
+        return RateLimitError(message, status=status, retry_after=retry_after, **kw)
+    if status >= 500:
+        return APIError(message, status=status, **kw)
+    return SerpbitError(message, status=status, **kw)

serpbit/_webhook.py

@@ -0,0 +1,24 @@
+"""Webhooks: a batch's events are signed with the API key that started it."""
+
+import hashlib
+import hmac
+import time
+from typing import Optional, Union
+
+
+def verify_webhook(body: Union[bytes, str], signature: Optional[str], api_key: str, *, tolerance: float = 300) -> bool:
+    """True when a webhook's body is Serpbit's, sent within tolerance seconds.
+
+    signature is the Serpbit-Signature header ("t=<unix>,v1=<hex>"); body is the request's raw body, as received.
+    """
+    if not signature or not api_key:
+        return False
+    parts = dict(p.split("=", 1) for p in signature.split(",") if "=" in p)
+    ts, sig = parts.get("t", ""), parts.get("v1", "")
+    if not ts.isdigit() or not sig:
+        return False
+    if tolerance and abs(time.time() - int(ts)) > tolerance:
+        return False
+    raw = body.encode() if isinstance(body, str) else body
+    want = hmac.new(api_key.encode(), ts.encode() + b"." + raw, hashlib.sha256).hexdigest()
+    return hmac.compare_digest(want, sig)

serpbit-0.1.0.dist-info/METADATA

@@ -0,0 +1,84 @@
+Metadata-Version: 2.4
+Name: serpbit
+Version: 0.1.0
+Summary: Google Search, News, Shopping, Images, Videos, Maps, Autocomplete and AI Mode as data: the Serpbit API client.
+Author-email: Serpbit <support@serpbit.com>
+License-Expression: MIT
+Project-URL: Homepage, https://serpbit.com
+Project-URL: Documentation, https://serpbit.com/docs/#sdks
+Project-URL: Changelog, https://serpbit.com/changelog/
+Keywords: serp,google search api,serp api,web search,ai agents,rag
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Internet :: WWW/HTTP :: Indexing/Search
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# serpbit
+
+Google Search, News, Shopping, Images, Videos, Maps, Autocomplete and AI Mode as data, from
+[Serpbit](https://serpbit.com). No dependencies: the standard library only, Python 3.9+.
+
+```sh
+pip install serpbit
+```
+
+```python
+from serpbit import Serpbit
+
+sb = Serpbit()  # reads SERPBIT_API_KEY; make a key at https://app.serpbit.com/keys
+
+answer = sb.search("espresso grinder", gl="de", hl="de", pages=2)
+for r in answer["organic"]:
+    print(r["position"], r["title"], r["url"])
+
+# The first three results' pages, as Markdown text: 1 credit a page read.
+answer = sb.search("how to descale an espresso machine", content=3)
+print(answer["organic"][0]["content"]["text"][:500])
+
+# Markdown instead of JSON, for a language model's context.
+print(sb.news("wildfire", sort="date", output="md"))
+```
+
+Every door of the API has a method: `search`, `news`, `shopping`, `shopping_product`, `images`, `videos`, `maps`,
+`autocomplete`, `ai_mode`. Keyword arguments are the door's parameters, as the [docs](https://serpbit.com/docs/)
+name them:
+- `True` is sent as `true`;
+- `None` and `False` are left out;
+- a list is joined with commas.
+
+A method returns the API's JSON as a dict, or a `str` with `output="md"`. `sb.last_request_id` and
+`sb.last_credits` give the last answer's id and the credits it spent.
+
+## Errors and retries
+
+A failed call raises a `SerpbitError`. The subclasses are:
+- `BadRequestError` (400);
+- `AuthenticationError` (401);
+- `InsufficientCreditsError` (402);
+- `RateLimitError` (429, with `retry_after`);
+- `APIError` (5xx);
+- `APIConnectionError`.
+
+Each carries `status`, `code` and `request_id`. Quote the `request_id` to support.
+
+Calls are retried twice on 429 and 5xx (set with `max_retries`), waiting as `Retry-After` says. Every attempt of one
+call carries the same `Idempotency-Key`, so an answer lost on the way is given back free instead of being billed
+twice. You can pass your own with `idempotency_key=`.
+
+## Batches
+
+```python
+b = sb.batch([{"path": "/v1/search", "params": {"q": kw, "gl": "us"}, "id": kw} for kw in keywords],
+             webhook="https://example.com/serpbit")
+sb.get_batch(b["id"])                     # status, and each call's
+sb.batch_results(b["id"], offset=0)       # the answers, 100 at a time, for a day after it ends
+
+# In your webhook: check the event is Serpbit's before you trust it.
+from serpbit import verify_webhook
+ok = verify_webhook(request.body, request.headers["Serpbit-Signature"], api_key)
+```

serpbit-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+serpbit/__init__.py,sha256=YFeiFUiubTNwOn5r-XxY3ERHLTVdPeFrPweP7LvaBU0,620
+serpbit/_client.py,sha256=KdFE_2EuYj_KINlghcl_GYKj8EJ4ax0yDOGi8k3SUTo,8964
+serpbit/_errors.py,sha256=CqgwJ9xlMz8YGxS6cgpVx9BB1WtVO5xJWkTWj1YbTcc,2533
+serpbit/_webhook.py,sha256=SohRR5COHJyxZamBKIQzZaS5VE-BgZmunGbXGUVIlfw,997
+serpbit/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+serpbit-0.1.0.dist-info/licenses/LICENSE,sha256=8_l_zG7x9IoJSOUDO9EWsYd5mUbic3B8FrL3-hsLQPE,1064
+serpbit-0.1.0.dist-info/METADATA,sha256=4eeCf7VJ7b4kDIE2sqIpGqp2PXNszq9DQEAz94tZ7Y8,3272
+serpbit-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+serpbit-0.1.0.dist-info/top_level.txt,sha256=ofxIRHP-BKSR-zLawYBppxLqIbqvrKLFxQKyk6yj7t8,8
+serpbit-0.1.0.dist-info/RECORD,,

serpbit-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

serpbit-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Serpbit
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

serpbit-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+serpbit