Official SDKs
Typed clients for Python and TypeScript with cursor iterators, automatic retries and typed errors.
Installation
Python
pip install scrapereviews-sdkTypeScript
npm install scrapereviewsQuick start
from scrapereviews import ScrapeReviews
# Or omit api_key and set SCRAPEREVIEWS_API_KEY
with ScrapeReviews(api_key="sr_your_api_key") as client:
company = client.companies.get("www.monzo.com")["data"]
print(company["name"], company["trust_score"])
page = client.companies.reviews("www.monzo.com", stars=[1, 2], language="en", limit=20)
for review in page["data"]:
print(review["rating"], review["title"])Responses are the JSON documented in the API reference (dicts in Python, typed objects in TypeScript), field names unchanged.
Client options
| Python | TypeScript | Default | Description |
|---|---|---|---|
| api_key | apiKey | $SCRAPEREVIEWS_API_KEY | Your API key (sr_...). Read from the environment when omitted. |
| base_url | baseUrl | https://api.scrapereviews.com | API base URL, or $SCRAPEREVIEWS_BASE_URL |
| timeout | timeout | 60 s / 60000 ms | Request timeout (seconds in Python, milliseconds in TypeScript) |
| max_retries | maxRetries | 2 | Automatic retries on 429 and 5xx, honoring Retry-After |
Python ships two clients with the same methods: ScrapeReviews (sync, usable with with) and AsyncScrapeReviews (async, usable with async with).
Methods
| Python | TypeScript | Endpoint |
|---|---|---|
| companies.search(query, limit=10, cursor=None) | companies.search(query, { limit, cursor }) | GET /v1/companies/search |
| companies.get(domain, include_similar=False) | companies.get(domain, { includeSimilar }) | GET /v1/companies/{domain} |
| companies.reviews(domain, stars, language, since, until, verified, with_reply, search, sort, limit, cursor) | companies.reviews(domain, { stars, language, since, until, verified, withReply, search, sort, limit, cursor }) | GET /v1/companies/{domain}/reviews |
| companies.iter_reviews(domain, **filters) | companies.iterReviews(domain, filters) | all pages of reviews |
| categories.list() | categories.list() | GET /v1/categories |
| categories.companies(category_id, country, sort, min_trust_score, location, limit, cursor) | categories.companies(categoryId, { country, sort, minTrustScore, location, limit, cursor }) | GET /v1/categories/{category_id}/companies |
| health_check() | healthCheck() | GET /health |
stars takes a list ([1, 2]); since / until take a date or a YYYY-MM-DD string.
Iterating over every review
iter_reviews / iterReviews follow meta.next_cursor for you and yield one review at a time, fetching pages of 100 (1 credit per 5 reviews, as usual). Stop the loop whenever you have enough: no further pages are requested.
from itertools import islice
# The 500 most recent negative reviews in English
for review in islice(client.companies.iter_reviews("www.monzo.com", stars=[1, 2], language="en"), 500):
print(review["published_at"], review["title"])Errors
Both SDKs raise the same error classes, mapped from the API error code. See Error Handling.
| Class | Raised on |
|---|---|
| ScrapeReviews | Base class of every error: status_code / statusCode, code, message, retry_after / retryAfter |
| InvalidParameterError | 400 invalid_parameter |
| AuthenticationError | 401 missing_api_key, invalid_api_key (or no key configured) |
| InsufficientCreditsError | 402 insufficient_credits, 429 insufficient_credits_retry_later |
| NotFoundError | 404 company_not_found, category_not_found |
| InvalidCursorError | 422 invalid_cursor |
| RateLimitError | 429 rate_limit_exceeded |
| UpstreamError | 502 / 503 / 504 upstream_* |