ScrapeReviews Python SDK
Official Python SDK for the ScrapeReviews API — Trustpilot company profiles, reviews and category rankings as clean JSON.
Installation
pip install scrapereviews-sdk
Quick Start
from scrapereviews import ScrapeReviews
client = ScrapeReviews(api_key="YOUR_API_KEY") # or set SCRAPEREVIEWS_API_KEY
# Company profile
company = client.companies.get("zalando.it").data
print(company.name, company.trust_score, company.review_count)
# Latest negative reviews
page = client.companies.reviews("zalando.it", stars=[1, 2], limit=20)
for review in page.data:
print(review.rating, review.title, review.published_at)
Async Usage
import asyncio
from scrapereviews import AsyncScrapeReviews
async def main():
async with AsyncScrapeReviews() as client:
async for review in client.companies.iter_reviews("zalando.it", max_reviews=200):
print(review.rating, review.text)
asyncio.run(main())
Configuration
| Argument | Environment variable | Default |
|---|---|---|
api_key |
SCRAPEREVIEWS_API_KEY |
required |
base_url |
SCRAPEREVIEWS_BASE_URL |
https://api.scrapereviews.com |
timeout |
— | 60 seconds |
max_retries |
— | 2 (rate limits and transient errors) |
API Reference
All methods return typed dataclasses (scrapereviews.models). Lists come with a meta
(credits_used, cache_hit, count, total, has_more, next_cursor): pass
meta.next_cursor as cursor to get the next page.
Companies
# Search by name or domain (1 credit per 10 results)
results = client.companies.search("zalando", limit=10)
next_page = client.companies.search("zalando", cursor=results.meta.next_cursor)
# Full profile (2 credits). Accepts a domain, a website URL or a Trustpilot URL.
company = client.companies.get("https://www.trustpilot.com/review/zalando.it", include_similar=True)
# One page of reviews (1 credit per 5 reviews)
page = client.companies.reviews(
"zalando.it",
stars=[1, 2], # or "1,2"
language="it", # "all" or ISO 639-1
since="2026-01-01", # date or YYYY-MM-DD / ISO 8601
until=None,
verified=False,
with_reply=False,
search="refund",
sort="recent", # or "relevant"
limit=100, # 1-100
)
# Every matching review, page by page (each page is billed as it is fetched)
for review in client.companies.iter_reviews("zalando.it", stars=[1], max_reviews=500):
...
Trustpilot shows at most 200 reviews per filter combination; the API splits the query by
star rating and language to go further. page.meta.complete is False when a single
(star, language) slice still held more than 200 reviews.
Categories
# Category tree (1 credit)
tree = client.categories.list()
# Company ranking of a category in a country (1 credit per 10 companies)
ranking = client.categories.companies(
"bank", "IT", sort="reviews_count", min_trust_score="4.0", location="Milano", limit=20
)
Error Handling
from scrapereviews import (
ScrapeReviews,
NotFoundError,
InsufficientCreditsError,
RateLimitError,
)
try:
company = client.companies.get("does-not-exist.invalid")
except NotFoundError as e:
print(e.code, e.message) # company_not_found, ...
except InsufficientCreditsError:
print("Top up your credits")
except RateLimitError as e:
print(f"Retry in {e.retry_after}s")
Exception Hierarchy
| Exception | HTTP Status | Description |
|---|---|---|
ScrapeReviewsError |
— | Base exception (message, status_code, code, retry_after) |
InvalidParameterError |
400 | Bad domain, stars, language, date... |
AuthenticationError |
401 | Missing or invalid API key |
InsufficientCreditsError |
402 / 429 | Credit balance is empty |
NotFoundError |
404 | Company or category not found (code tells which) |
InvalidCursorError |
422 | Cursor malformed or made for other filters |
RateLimitError |
429 | Too many requests (retry_after seconds) |
UpstreamError |
502 / 503 / 504 | Trustpilot unreachable, slow or changed |
Rate limits (429) and transient errors (500, 503, 504) are retried up to max_retries times,
honouring Retry-After. Failed calls cost no credits.
Credits
Every response carries what it cost in meta.credits_used; the client also exposes the
X-Credits-Used header of the last request:
client.companies.get("zalando.it")
print(client.credits_used) # 2
Development
uv venv -p 3.12 && uv pip install -e ".[dev]"
.venv/bin/pytest && .venv/bin/ruff check .
# Manual test against the live API (spends ~15 credits)
SCRAPEREVIEWS_API_KEY=... python live_test.py
License
MIT
Metadata
Release files for scrapereviews-sdk 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| scrapereviews_sdk-0.1.0.tar.gz | 17.8 kB | Without provenance | Details for scrapereviews_sdk-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| scrapereviews_sdk-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for scrapereviews_sdk-0.1.0-py3-none-any.whl |
Total release size: 34.3 kB
Release files / scrapereviews_sdk-0.1.0.tar.gz
| Download URL | scrapereviews_sdk-0.1.0.tar.gz |
|---|---|
| Size | 17.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
29235cc124701049675767993743908c49b39b4695ee1a22b41372040eccd4db
|
|
BLAKE2b-256 checksum How to use checksums |
69653cb556ae70f03a63f438bff9d0e478fa56737268167d7480af4ca6f71ce2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.10.12 {"installer":{"name":"uv","version":"0.10.12","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / scrapereviews_sdk-0.1.0-py3-none-any.whl
| Download URL | scrapereviews_sdk-0.1.0-py3-none-any.whl |
|---|---|
| Size | 16.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
d237f5aaa58cac7794b2019919587c0f568b00edc91dd9661b98fa3e2b6dee90
|
|
BLAKE2b-256 checksum How to use checksums |
52ace3798dd821ca0bb255afaad14953c9772bb589388f0b9a2b7c257e03bca4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.10.12 {"installer":{"name":"uv","version":"0.10.12","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for scrapereviews-sdk 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.