Keyword ranking summary of a day

GET /keyword-rankings/summary

Returns the Google Maps ranking summary of a shop for a day (defaults to the latest snapshot), per tracked keyword: average rank across the scanned geo points, rank at the center point, share of points in the top 3 and top 7, and coverage (share of points where the shop appears at all). Ranks go from 1 to 20; a point where the shop is out of the top 20 counts as 21, so always read average_rank together with coverage. Keywords are sorted best first.

Requires the keyword_tracking:read scope.

Returns a single object (no pagination). Answers a 404 problem when no snapshot exists for the shop, keyword or day. Pass a keyword from the keywords returned by /keyword-tracking.

Example request


curl "https://api.dokaa.app/v1/keyword-rankings/summary?shop_id=SHOP_ID" \
  -H "Authorization: Bearer dk_live_..."

Query parameters

shop_id (string, required) – The shop to inspect
keyword (string) – Restrict to one tracked keyword (all tracked keywords if omitted)
date (string) (format: date) – Snapshot day (UTC). Omit to use the most recent snapshot

Responses

200 – Per-keyword ranking summary of the day


{
  "date": "2026-08-05",
  "keyword_count": 2,
  "best": {
    "keyword": "pizza lille",
    "average_rank": 4.2
  },
  "worst": {
    "keyword": "restaurant lille",
    "average_rank": 15.8
  },
  "keywords": [
    {
      "keyword": "pizza lille",
      "average_rank": 4.2,
      "center_rank": 2,
      "top3_rate": 45.5,
      "top7_rate": 81.8,
      "coverage": 100,
      "found_points": 11,
      "scanned_points": 11,
      "scanned_at": "2026-08-05T04:12:00Z"
    },
    {
      "keyword": "restaurant lille",
      "average_rank": 15.8,
      "center_rank": 12,
      "top3_rate": 0,
      "top7_rate": 9.1,
      "coverage": 36.4,
      "found_points": 4,
      "scanned_points": 11,
      "scanned_at": "2026-08-05T04:15:00Z"
    }
  ]
}

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.