# Review analytics

`GET /analytics/reviews`

Returns aggregates computed server-side over the platform reviews of
one shop (`shop_id`) or all your shops: total count, average rating,
star distribution, reply rate, and the same figures per platform.
Without `from`/`to`, aggregates cover the whole history.

Requires the `reviews:read` scope.

**Returns** a single object: totals, a `rating_distribution` keyed by
stars `1` to `5`, a `reply_rate` in percent, and a `platforms`
array carrying the same figures per platform. Counts are `0` and
averages `null` when no review matches.

Unlike `/reviews`, this endpoint covers external platform reviews only;
Dokaa satisfaction surveys are aggregated by `/analytics/feedbacks`.

## Example request

```bash
curl "https://api.dokaa.app/v1/analytics/reviews" \
  -H "Authorization: Bearer dk_live_..."
```

## Query parameters

- `shop_id` (string) – Restrict to a single shop (omit to query all your shops)
- `platform` (string) (one of: google, deliveroo, ubereats, tripadvisor, fork) – Restrict to a single platform
- `from` (string) (format: date) – Only reviews posted on or after this date
- `to` (string) (format: date) – Only reviews posted on or before this date

## Responses

### 200 – Review aggregates

```json
{
  "review_count": 4572,
  "average_rating": 4.6,
  "reply_count": 3980,
  "reply_rate": 87.1,
  "rating_distribution": {
    "1": 128,
    "2": 87,
    "3": 133,
    "4": 526,
    "5": 3698
  },
  "platforms": [
    {
      "platform": "google",
      "review_count": 3076,
      "average_rating": 4.7,
      "rating_distribution": {
        "1": 60,
        "2": 40,
        "3": 80,
        "4": 350,
        "5": 2546
      }
    },
    {
      "platform": "ubereats",
      "review_count": 1087,
      "average_rating": 4.5,
      "rating_distribution": {
        "1": 45,
        "2": 30,
        "3": 40,
        "4": 130,
        "5": 842
      }
    }
  ]
}
```

### 401 – Missing, invalid, or revoked API key

### 403 – The API key does not grant access to this resource

### 422 – Invalid request parameters

Errors are `application/problem+json` (RFC 9457) with `type`, `title`, `status` and `detail` fields.