# Competitor positioning of a shop

`GET /competitors/positioning`

Returns where a shop stands versus its tracked competitors on a given
day (defaults to the latest available snapshot): the shop rating and
review count with its rank in the panel, the gap to the leader and to
the panel average, the average rating of the reviews received (weighted
from the star breakdown, unlike the cumulative Google rating), and the
same figures per competitor. Answers "where do I stand against my
competitors?".

Requires the `competitors:read` scope.

**Returns** a single object (no pagination). Answers a `404` problem
when no snapshot exists for the shop or the requested day.

## Example request

```bash
curl "https://api.dokaa.app/v1/competitors/positioning?shop_id=SHOP_ID" \
  -H "Authorization: Bearer dk_live_..."
```

## Query parameters

- `shop_id` (string, required) – The shop to inspect
- `date` (string) (format: date) – Snapshot day (UTC). Omit to use the most recent snapshot

## Responses

### 200 – The positioning of the shop in its competitor panel

```json
{
  "date": "2026-08-05",
  "panel_size": 3,
  "target": {
    "name": "Pizza Marcel",
    "google_place_id": "ChIJN1t_tDeuEmsRUsoyG83frY4",
    "rating": 4.6,
    "review_count": 1240,
    "reviews_average": 4.4,
    "price_range": "€€",
    "rating_rank": 1,
    "review_count_rank": 1,
    "rating_vs_panel_average": 0.23,
    "rating_gap_to_leader": 0
  },
  "panel": {
    "rating_average": 4.37,
    "review_count_average": 811.67,
    "leader": {
      "name": "Pizza Marcel",
      "rating": 4.6
    }
  },
  "competitors": [
    {
      "name": "Rival A",
      "google_place_id": "ChIJrTLr-GyuEmsRBfy61i59si0",
      "rating": 4.4,
      "review_count": 890,
      "reviews_average": 4.2,
      "price_range": "€€",
      "rating_rank": 2,
      "review_count_rank": 2
    }
  ]
}
```

### 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.