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


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


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