litescrape-sdk

Python SDK for the Litescrape API: validated, concurrent, retrying calls to the Google, Bing, DuckDuckGo, Yelp, Tripadvisor, Apple Maps, Google Play, and Apple App Store endpoints, with results returned in input order.

pip install litescrape-sdk

import os
from litescrape_sdk import GoogleMaps, scrape

os.environ["LITESCRAPE_API_KEY"] = "ls_live_..."

results = scrape(
    [
        {"endpoint": "google_search", "q": "coffee grinders", "gl": "us"},
        GoogleMaps(q="coffee", type="search", ll="@40.745,-73.988,14z"),
    ]
)
for result in results:
    print(result.ok, result.data or result.error)

help(litescrape_sdk.scrape) documents every argument, the retry and concurrency rules, and the error types. ascrape is the same function for asyncio code, and litescrape_sdk.REQUEST_TYPES maps each endpoint slug to its request class.

Development: uv sync, then uv run pytest, uv run ruff check ., and uv run ruff format ..

Google Search fast mode

Google Search supports GoogleSearch(q="coffee grinders", fast_mode=True) to return only organic results plus search metadata and parameters. This skips AI Overview and other result groups. The default is the full response; fast mode is unavailable on the dedicated AI Overview endpoint. Requires an API deployment that supports fast_mode.

Request deadlines

Set request_timeout on scrape or ascrape to apply a server deadline to every item. Set timeout on an individual request to override that default. Both accept seconds greater than 0 and at most 90, including fractional seconds; omitting them preserves the API's standard behavior.

from litescrape_sdk import GoogleSearch, RequestDeadlineExceededError, scrape

(result,) = scrape(
    [GoogleSearch(q="coffee grinders")],
    request_timeout=15,
    attempts=1,
)
if isinstance(result.error, RequestDeadlineExceededError):
    print(result.error.request_id, result.error.retryable, result.error.message)
else:
    print(result.raise_for_error())

# A per-item deadline also works in dictionaries.
results = scrape(
    [
        GoogleSearch(q="coffee", timeout=10),
        {"endpoint": "google_search", "q": "tea", "timeout": 20},
    ],
    attempts=1,
)

The deadline covers the entire API request from gateway receipt, including admission, scraping, and billing. On expiry, the API returns HTTP 503 with the new request_deadline_exceeded code, retryable: true, a request ID, and a description. That attempt is not charged. The API cancels the underlying scrape to release concurrency; credit and concurrency cleanup can finish shortly after the response.

The SDK retries this response using its usual attempts and Retry-After rules. Each attempt gets its own deadline; use attempts=1 as above to receive the first timeout immediately. SDK queueing, the status check, network transit, retry waits, and the full batch are outside the server deadline.

The existing scrape(..., timeout=120) argument remains the HTTP transport timeout. Keep it longer than the server deadline so the API can return its error. A client-side TransportError alone does not guarantee that the request was unbilled.

Store APIs (Alpha)

All nine Store operations use your existing key. Alpha fields depend on what the storefront supplies.

from litescrape_sdk import GooglePlayApps, GooglePlayProduct, AppleAppStoreSearch, scrape

results = scrape(
    [
        GooglePlayApps(q="coffee", hl="en", gl="us"),
        GooglePlayProduct(product_id="com.duolingo"),
        AppleAppStoreSearch(term="coffee", country="us", num=10),
    ]
)
for result in results:
    print(result.raise_for_error())

Follow litescrape_pagination.next or use the returned continuation with the same operation and parameters. Each successful page consumes one call; failures do not. For Google Play, chart, next_page_token, section_page_token, and see_more_token are mutually exclusive. Queries exclude category filters and charts. Search text is limited to 2,048 UTF-8 bytes, so non-ASCII characters can consume more than one byte. Apple search also limits URL-encoded terms to 4,096 bytes. Apps/games charts require store_device="phone" or an omitted device; other device storefronts are browsable without a chart. Omit store_device when using an apps or games query or category. GooglePlayGames(q=...) uses the shared Android app search; omit q or choose games_category to browse games. Apple review pages are one-based; exhausted pages return an empty list. Mac reviews use newest-first ordering.

search_metadata.raw_file and prettify_file, when returned, link to authenticated response artifacts retained for at least seven days (today and the previous seven UTC date buckets). Download them with the same bearer key; downloads are unbilled. Apple search applies category and case-insensitive developer-name filters before the num ceiling. The native search window can contain fewer matching results than that ceiling. See the API reference for every parameter and response group.