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


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


{
  "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.