Official SDKs

Typed clients for Python and TypeScript with cursor iterators, automatic retries and typed errors.

Installation

Python

pip install scrapereviews-sdk

TypeScript

npm install scrapereviews

Quick 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

PythonTypeScriptDefaultDescription
api_keyapiKey$SCRAPEREVIEWS_API_KEYYour API key (sr_...). Read from the environment when omitted.
base_urlbaseUrlhttps://api.scrapereviews.comAPI base URL, or $SCRAPEREVIEWS_BASE_URL
timeouttimeout60 s / 60000 msRequest timeout (seconds in Python, milliseconds in TypeScript)
max_retriesmaxRetries2Automatic 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

PythonTypeScriptEndpoint
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.

ClassRaised on
ScrapeReviewsBase class of every error: status_code / statusCode, code, message, retry_after / retryAfter
InvalidParameterError400 invalid_parameter
AuthenticationError401 missing_api_key, invalid_api_key (or no key configured)
InsufficientCreditsError402 insufficient_credits, 429 insufficient_credits_retry_later
NotFoundError404 company_not_found, category_not_found
InvalidCursorError422 invalid_cursor
RateLimitError429 rate_limit_exceeded
UpstreamError502 / 503 / 504 upstream_*

Next Steps