Official SDKs

The official ScrapeMapsAPI clients for Python and TypeScript: typed results, automatic cursor paging, retries on temporary errors and clear exceptions.

Why use an SDK

The API is plain HTTP and JSON, so any HTTP client works. The SDKs save the code every integration ends up writing: they send the API key, build the query string, turn the JSON into typed objects that match the response field by field, follow next_cursor until the last page, and retry the temporary errors (429, 502 and 503) with exponential backoff, honouring Retry-After.

Both SDKs read the key from the SCRAPEMAPSAPI_API_KEY environment variable when you do not pass one, expose the credits used and remaining on every result, and raise one error class per error code, so a missing place, an exhausted balance and a network failure can each be handled on their own. Both are MIT licensed: the Python SDK depends only on httpx, the TypeScript SDK only on the built-in fetch.

Installation

Python 3.9+

pip install scrapemapsapi

TypeScript / Node 18+

npm install scrapemapsapi

Quick Start

Search a place, read its details and its newest reviews. The client reads SCRAPEMAPSAPI_API_KEY when no key is passed.

from scrapemapsapi import ScrapeMapsAPI

client = ScrapeMapsAPI(api_key="key_your_api_key")

results = client.places.search(q="trattoria in Florence", region="it", limit=5)
for place in results.data:
    print(place["name"], place["rating"], place["id"])

place = client.places.get("ChIJ8cLgoQNUKhMReGlaTjwrH40", language="en")
print(place["address"]["formatted"], place["opening_hours"]["status_text"])

page = client.places.reviews("ChIJ8cLgoQNUKhMReGlaTjwrH40", sort="newest", limit=20)
for review in page.data:
    print(review["rating"], review["text"])

Every review, without handling cursors

iter_reviews / iterReviews follow next_cursor for you and stop on the last page. Use max_items / maxItems to cap the spend.

for review in client.places.iter_reviews("ChIJ8cLgoQNUKhMReGlaTjwrH40", sort="newest", language="en", max_items=1000):
    print(review["published_at"], review["rating"], review["translated_text"] or review["text"])

Resolve Google Maps links

ids = client.places.resolve("https://maps.app.goo.gl/x7Qp2Nf9TzVb8LkE6")
print(ids["place_id"], ids["cid"], ids["feature_id"])

Async Support (Python)

Python
import asyncio
from scrapemapsapi import AsyncScrapeMapsAPI

async def main():
    async with AsyncScrapeMapsAPI() as client:
        places = ["ChIJ8cLgoQNUKhMReGlaTjwrH40", "10168894021638449528"]
        details = await asyncio.gather(*(client.places.get(p) for p in places))
        for place in details:
            print(place["name"], place["review_count"])

asyncio.run(main())

Error Handling

Errors raise typed exceptions carrying the HTTP status and the API error code, read from the {"detail": {"error", "message"}} body of the response. Temporary errors (429, 502, 503) are retried automatically before raising. A 422 validation error, whose detail is a list of invalid parameters, becomes an InvalidRequestError with the code validation_error and the parameter names in its message. Every code is listed in Error Handling.

from scrapemapsapi import (
    ScrapeMapsAPIError,
    InsufficientCreditsError,
    NotFoundError,
)

try:
    place = client.places.get("10168894021638449528")
except NotFoundError:
    print("place_not_found")
except InsufficientCreditsError:
    print("Top up your credits")
except ScrapeMapsAPIError as e:
    print(e.status_code, e.code, e.message)

Response Metadata

List results expose data, pagination and meta; the credits charged and the remaining balance come from the response headers.

page = client.places.reviews("ChIJ8cLgoQNUKhMReGlaTjwrH40", limit=20)
print(page.meta["credits_used"], page.credits_remaining, page.pagination["has_more"])

Configuration

Both clients accept api_key/apiKey, base_url/baseUrl (default https://api.scrapemapsapi.com), timeout and max_retries/maxRetries. They also read SCRAPEMAPSAPI_API_KEY and SCRAPEMAPSAPI_BASE_URL from the environment.

Resources