# Competitor evolution over a period

`GET /competitors/evolution`

Tracks how a shop and its competitors evolved over a period: reviews
gained, rating delta, and share of voice (the shop's share of all new
reviews captured by the panel). The shop's daily series is always
included; pass `include_series=true` to also get every competitor's
series. Snapshots are daily, so use a range of several days (366 days
maximum).

Requires the `competitors:read` scope.

**Returns** a single object (no pagination). Answers a `404` problem
when the period holds no snapshot.

## Example request

```bash
curl "https://api.dokaa.app/v1/competitors/evolution?shop_id=SHOP_ID&from=FROM&to=TO" \
  -H "Authorization: Bearer dk_live_..."
```

## Query parameters

- `shop_id` (string, required) – The shop to inspect
- `from` (string, required) (format: date) – First day of the period (UTC)
- `to` (string, required) (format: date) – Last day of the period (UTC)
- `include_series` (boolean) (default: false) – Also include the daily series of every competitor (verbose)

## Responses

### 200 – Reviews gained, rating deltas and share of voice over the period

```json
{
  "period": {
    "from": "2026-07-01",
    "to": "2026-08-05"
  },
  "panel_size": 3,
  "panel": {
    "total_reviews_gained": 100
  },
  "target": {
    "name": "Pizza Marcel",
    "google_place_id": "ChIJN1t_tDeuEmsRUsoyG83frY4",
    "reviews_gained": 30,
    "rating_delta": 0.2,
    "first_rating": 4.4,
    "last_rating": 4.6,
    "last_review_count": 1240,
    "share_of_voice": 30,
    "series": [
      {
        "date": "2026-07-01",
        "rating": 4.4,
        "review_count": 1210
      },
      {
        "date": "2026-08-05",
        "rating": 4.6,
        "review_count": 1240
      }
    ]
  },
  "competitors": [
    {
      "name": "Rival A",
      "google_place_id": "ChIJrTLr-GyuEmsRBfy61i59si0",
      "reviews_gained": 70,
      "rating_delta": 0,
      "first_rating": 4.4,
      "last_rating": 4.4,
      "last_review_count": 890,
      "share_of_voice": 70
    }
  ]
}
```

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

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

### 404 – The requested resource does not exist or is not accessible

### 422 – Invalid request parameters

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