trustpilot-reviews

# Trustpilot — Reviews

> Input a company domain plus optional filters → output paginated review records with reviewer info, ratings, dates, company replies, and 20+ structured fields per review.

## Language

All process output to user (progress updates, process notifications) follows the user's language.

## Objective

Extract one page of customer reviews from `trustpilot.com/review/{domain}` with the chosen filters applied. Designed to be called in a loop across pages to collect the full filtered review set.

## Prerequisites

- Target page is reachable on the public web: `https://www.trustpilot.com/review/{domain}`
- No login required — Trustpilot review pages are publicly accessible

## Pre-execution Checks

### 1. Tool Readiness

If browser-act has been confirmed available in the current session → skip this step.

Invoke `browser-act` via Skill tool to load usage. If installation or configuration issues arise, follow its guidance to resolve then retry.

## Capability Components

> This Skill's operational boundary = what the user can manually do in their browser. It only reads data already displayed to the user on the page, never bypassing authentication or access controls. JS code is encapsulated in Python files under the `scripts/` directory, invoked via `eval "$(python scripts/xxx.py {params})"`. `$(...)` is bash syntax; it is recommended to use the bash tool for execution.

### URL Pattern (server-side filters)

Trustpilot accepts filter values as URL query parameters. Build the URL before navigating:

```
https://www.trustpilot.com/review/{domain}?page={page}&languages={lang}&sort=recency&stars={stars}&verified={true|false}&replies={true|false}&date={period}&search={keyword}
```

All parameters except `domain` are optional. Recommended construction rules:
- `page`: integer ≥ 1 (omit for page 1; pagination defaults to 20 per page)
- `languages`: single ISO code (e.g. `en`, `da`, `de`, `es`, `fr`); omit or use `all` for no language filter
- `sort`: only `recency` is currently honoured by the public review page (older `relevancy` values are stripped on redirect)
- `stars`: single value `1`, `2`, `3`, `4`, or `5` — only one star tier can be selected
- `verified`: `true` to keep only verified reviews
- `replies`: `true` to keep only reviews that received a company response
- `date`: one of `last30days`, `last3months`, `last6months`, `last12months`
- `search`: URL-encoded keyword to search inside review text

Country-of-reviewer filtering is **not supported by Trustpilot's URL** — it is applied client-side after extraction using `--filter-country` (see below).

### DOM: extract reviews from current page (SSR JSON)

The Trustpilot review page is server-rendered with Next.js; the full reviews array is embedded in `<script id="__NEXT_DATA__">`. Extraction reads it directly — no separate API call needed.

Steps:
1. Build the URL as described above.
2. `navigate {built-url}`
3. `wait stable --timeout 30000`
4. `eval "$(python scripts/extract-reviews.py [options])"`

Parameters (all optional flags / values):
- `--include-reviewer-metadata`: adds `reviewerNumberOfReviews`, `reviewerProfileIsVerified`.
- `--include-reply-analysis`: adds `companyReplyPublishedDate`, `companyReplyUpdatedDate` (null when no reply).
- `--include-extended-metadata`: adds `reviewSource` (e.g. `Organic`, `Shopify`, `InvitationApi`), `reviewVerificationSource` (e.g. `invitation`, `complianceDocumentation`), `reviewLikes`.
- `--include-review-photos`: adds `reviewPhotoUrls` array via best-effort DOM scan of the review card; returns `[]` when no photos.
- `--no-experience-date`: omit the default `reviewDateOfExperience` field.
- `--filter-country {ISO2}`: client-side filter — keep only reviews whose reviewer `countryCode` matches the given ISO Alpha-2 code (e.g. `US`, `GB`, `DK`). Case-insensitive. Applied after the page-level filters from the URL.

Output example (one page, with all optional flags):
```json
{
  "reviews": [                                              // array of review objects (≤ perPage items)
    {
      "companyName": "Wag + Tail",
      "companyPageUrl": "https://www.trustpilot.com/review/shopwagandtail.com?page=1&languages=en",
      "businessUnitId": "624c24851220e2743a4d7916",         // Trustpilot internal company ID
      "reviewId": "65fd6a055de8c560404349e1",
      "reviewUrl": "https://www.trustpilot.com/reviews/65fd6a055de8c560404349e1",
      "reviewTitle": "Great product looks so cute on my girl",
      "reviewDescription": "Great product looks so cute on my girl and fits so well",
      "reviewRatingScore": 5,                                // 1-5
      "reviewDate": "2024-03-22T13:22:45.000Z",              // when review was posted
      "reviewLabel": "verified",                             // "verified" or "not-verified"
      "isReviewVerified": true,
      "reviewer": "Angela Rosalie",
      "reviewerId": "656cc367ad3fb4001307cba8",
      "reviewersCountry": "US",                              // ISO Alpha-2
      "reviewLanguage": "en",
      "reviewCompanyResponse": "",                           // empty string when no reply
      "scrapedDateTime": "2026-06-26T04:13:03.026Z",
      "scrapedAtReviewPageNumber": 1,
      "reviewDateOfExperience": "2024-01-27T00:00:00.000Z",  // default; remove with --no-experience-date
      "reviewerNumberOfReviews": 2,                          // --include-reviewer-metadata
      "reviewerProfileIsVerified": false,                    // --include-reviewer-metadata
      "companyReplyPublishedDate": null,                     // --include-reply-analysis (null when no reply)
      "companyReplyUpdatedDate": null,                       // --include-reply-analysis
      "reviewSource": "Shopify",                             // --include-extended-metadata
      "reviewVerificationSource": "invitation",              // --include-extended-metadata
      "reviewLikes": 0,                                      // --include-extended-metadata
      "revi