Category companies endpoint
https://api.scrapereviews.com/v1/categories/{category_id}/companies1 credit per 10 companies (min 1)The category companies endpoint returns the ranking Trustpilot shows on a category page: the companies of one category in one country, for example the banks of the United Kingdom or the shoe stores of Italy.
Sort by relevance (Trustpilot's own order, the default) or by number of reviews, keep only companies with a TrustScore of at least 3.0, 4.0 or 4.5, and narrow the list to a city with location. Each result is a CompanySummary with the domain to use in the profile and reviews endpoints.
The country is required and is an ISO 3166-1 alpha-2 code such as GB, US, DE or IT. Category ids come from the category tree endpoint. Results are paginated with a cursor, like every list endpoint.
Parameters
Path parameters
| Parameter | Type | Description |
|---|---|---|
| category_id | string | A category id from /v1/categories, e.g. bank |
Query parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
| country | string | required | ISO 3166-1 alpha-2, e.g. IT |
| sort | relevant | reviews_count | relevant | Order of the companies |
| min_trust_score | 3.0 | 4.0 | 4.5 | - | Only companies with at least this TrustScore |
| location | string ≤ 100 | - | City, e.g. Milano |
| limit | integer 1-100 | 20 | Companies per response |
| cursor | string | - | meta.next_cursor of the previous response, with the same filters |
Authenticate with your API key in the X-API-Key header or as Authorization: Bearer (see authentication).
Example request
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"Response
{ "category": { "id": "bank", "name": "Bank", "country": "GB" }, "data": CompanySummary[], "meta": ListMeta }{
"category": { "id": "bank", "name": "Bank", "country": "GB" },
"data": [
{
"id": "5130a5e4000064000525c7e9",
"domain": "www.monzo.com",
"name": "Monzo",
"trust_score": 4.6,
"stars": 4.5,
"review_count": 74600,
"categories": [{ "id": "bank", "name": "Bank", "is_primary": true }],
"trustpilot_url": "https://www.trustpilot.com/review/www.monzo.com"
}
],
"meta": { "credits_used": 2, "cache_hit": false, "count": 20, "total": 167,
"has_more": true, "next_cursor": "eyJ..." }
}Every field is described in the response models. Successful responses also carry the X-Credits-Used header.
Cost
Category rankings are billed by volume: 1 credit per 10 companies (min 1). A page of 20 companies costs 2 credits, a page of 100 costs 10.
Only successful calls are billed: every error costs 0 credits. You get 100 free credits every month; see pricing for credit packs.
Errors
Errors come with an HTTP status and this JSON body: branch on detail.error, show detail.message to humans.
{
"detail": {
"error": "category_not_found",
"message": "Category 'banks' not found"
}
}| HTTP | error | Meaning |
|---|---|---|
| 400 | invalid_parameter | A parameter is invalid: bad domain, stars, language or date, missing query, limit out of range... |
| 401 | missing_api_key | No API key in X-API-Key or Authorization: Bearer. |
| 401 | invalid_api_key | The key does not exist or has been revoked. |
| 402 | insufficient_credits | Your credit balance is 0. |
| 404 | category_not_found | The category id does not exist. |
| 422 | invalid_cursor | The cursor is malformed, tampered with, or was created for other filters. |
| 429 | rate_limit_exceeded | Too many requests per minute. |
| 429 | insufficient_credits_retry_later | The balance ran out on recent calls and the key is cooling down. |
| 502 | upstream_changed | Trustpilot changed its page format and the response could not be read. |
| 503 | upstream_blocked | Trustpilot is temporarily blocking requests. |
| 504 | upstream_timeout | Trustpilot did not answer in time. |
What to do for each code: error handling.
Use cases
- Build a list of the best rated companies of a sector in a country for market research.
- Find competitors of a company: same category, same country, sorted by number of reviews.
- Generate local leads: the companies of a category in one city with a TrustScore of at least 4.0.
Related endpoints
- Category tree GET /v1/categories: The full category tree. Use the ids with the category companies endpoint.
- Company profile GET /v1/companies/{domain}: The full profile of a company: TrustScore, star distribution, languages, categories, contacts, claim status and reply behavior.
ScrapeReviews is an independent service and is not affiliated with or endorsed by Trustpilot.