Skip to main content

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)

Source distribution for scrapereviews-sdk 0.1.0
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)

Table of built distributions (wheels) for scrapereviews-sdk 0.1.0
File Interpreter ABI Platform Actions
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.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page