Code Examples

cURL, Python and TypeScript examples for every endpoint, plus two complete use cases.

PythonPyPI
pip install scrapereviews-sdk
TypeScriptnpm
npm install scrapereviews

Get a company profile

TrustScore, star distribution, review languages, reply behavior and contacts. Any URL of the site works as the domain.

curl "https://api.scrapereviews.com/v1/companies/www.monzo.com?include_similar=true" \
  -H "X-API-Key: sr_your_api_key"
Example response
{
  "data": {
    "domain": "www.monzo.com",
    "name": "Monzo",
    "trust_score": 4.6,
    "review_count": 74600,
    "star_distribution": { "one": 7462, "two": 856, "three": 1069, "four": 4380, "five": 60833 },
    "languages": [{ "language": "en", "count": 70000 }],
    "reply_behavior": { "reply_rate": 51.07, "average_days_to_reply": 2.9 },
    "similar": [ ... ]
  },
  "meta": { "credits_used": 2, "cache_hit": false }
}

Reviews with filters

Combine stars, language, since/until, verified, with_reply, search and sort. Each response costs 1 credit per 5 reviews.

curl -G "https://api.scrapereviews.com/v1/companies/www.monzo.com/reviews" \
  -H "X-API-Key: sr_your_api_key" \
  --data-urlencode "stars=1,2" \
  --data-urlencode "language=en" \
  --data-urlencode "since=2026-10-01" \
  --data-urlencode "until=2026-10-31" \
  --data-urlencode "verified=true" \
  --data-urlencode "with_reply=true" \
  --data-urlencode "search=card blocked" \
  --data-urlencode "sort=recent" \
  --data-urlencode "limit=50"
Example response
{
  "company": { "id": "...", "domain": "www.monzo.com", "name": "Monzo", "trust_score": 4.6, "review_count": 74600, "trustpilot_url": "..." },
  "data": [
    {
      "id": "6aff80ab97bf06512078aeb5",
      "rating": 1,
      "title": "...",
      "text": "...",
      "language": "en",
      "published_at": "2026-10-20T01:05:15.000Z",
      "is_verified": true,
      "author": { "id": "u_03c1fd2a7b494fcd43a7", "country": "GB", "review_count": 2, "is_verified": false },
      "reply": { "text": "...", "published_at": "...", "updated_at": null },
      "url": "https://www.trustpilot.com/reviews/6aff80ab97bf06512078aeb5"
    }
  ],
  "meta": { "credits_used": 10, "cache_hit": false, "count": 50, "total": 61, "has_more": true, "next_cursor": "eyJ...", "complete": true }
}

Paginate all reviews

Follow meta.next_cursor while meta.has_more is true, keeping the same filters. The SDK iterators (iter_reviews / iterReviews) do it for you and yield one review at a time.

cursor=""
while :; do
  resp=$(curl -s -G "https://api.scrapereviews.com/v1/companies/www.monzo.com/reviews" -H "X-API-Key: sr_your_api_key" \
    --data-urlencode "stars=1" --data-urlencode "limit=100" \
    ${cursor:+--data-urlencode "cursor=$cursor"})
  echo "$resp" | jq -c '.data[]' >> reviews.jsonl
  [ "$(echo "$resp" | jq -r '.meta.has_more')" = "true" ] || break
  cursor=$(echo "$resp" | jq -r '.meta.next_cursor')
done

Categories and category companies

Get the category tree, then list the companies of a category in a country, filtered by min_trust_score and sorted by relevant or reviews_count.

# Category tree (1 credit)
curl "https://api.scrapereviews.com/v1/categories" -H "X-API-Key: sr_your_api_key"

# Banks in the UK with TrustScore >= 4.0, most reviewed first
curl "https://api.scrapereviews.com/v1/categories/bank/companies?country=GB&min_trust_score=4.0&sort=reviews_count&limit=20" \
  -H "X-API-Key: sr_your_api_key"
Example response
{
  "category": { "id": "bank", "name": "Bank", "country": "GB" },
  "data": [ { "domain": "www.monzo.com", "name": "Monzo", "trust_score": 4.6, "review_count": 74600, ... } ],
  "meta": { "credits_used": 2, "cache_hit": false, "count": 20, "total": 87, "has_more": true, "next_cursor": "eyJ..." }
}

Error handling

Errors raise typed exceptions extending ScrapeReviews. Failed calls cost no credits; the SDKs already retry rate limits and transient upstream errors. See all error codes.

curl -s -w "\nHTTP %{http_code}\n" "https://api.scrapereviews.com/v1/companies/does-not-exist.example" -H "X-API-Key: sr_your_api_key"
# {"detail":{"error":"company_not_found","message":"..."}}
# HTTP 404

Use cases

Export last month's 1-star reviews to CSV

All 1-star reviews published in the last 30 days, in every language, written to a CSV file.

import csv
from datetime import date, timedelta
from scrapereviews import ScrapeReviews

client = ScrapeReviews(api_key="sr_your_api_key")

since = date.today() - timedelta(days=30)

with open("one_star_reviews.csv", "w", newline="", encoding="utf-8") as f:
    writer = csv.writer(f)
    writer.writerow(["published_at", "language", "author_country", "title", "text", "replied", "url"])
    for r in client.companies.iter_reviews("www.monzo.com", stars=[1], since=since):
        writer.writerow([
            r["published_at"], r["language"], r["author"]["country"],
            r["title"], r["text"], bool(r["reply"]), r["url"],
        ])

Compare competitors' TrustScores in a category

Rank the most reviewed companies of a category in a country, with their TrustScore and share of 1-star reviews.

from scrapereviews import ScrapeReviews

client = ScrapeReviews(api_key="sr_your_api_key")

companies = client.categories.companies("bank", country="GB", sort="reviews_count", limit=10)["data"]

rows = []
for c in companies:
    profile = client.companies.get(c["domain"])["data"]
    dist = profile["star_distribution"]
    total = sum(dist.values()) or 1
    rows.append((profile["name"], profile["trust_score"], profile["review_count"], dist["one"] / total))

for name, score, count, one_star in sorted(rows, key=lambda r: r[1], reverse=True):
    print(f"{name:30} {score:>4}  {count:>8} reviews  {one_star:6.1%} 1-star")