# 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

```bash
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

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