# Keyword ranking trend over a period

`GET /keyword-rankings/trend`

Tracks how a shop's Google Maps ranking evolved over a period (366 days
maximum) for one tracked keyword: daily average rank across the scanned
points, rank at the center, top-3 share and coverage, plus the delta
between the first and last day. Snapshots are daily (UTC). Ranks are
inverted: a negative `rank_delta` means the ranking improved.

Requires the `keyword_tracking:read` scope.

**Returns** a single object (no pagination). Answers a `404` problem
when the period holds no snapshot for the keyword. The `keyword` must
be one of the `keywords` returned by `/keyword-tracking`.

## Example request

```bash
curl "https://api.dokaa.app/v1/keyword-rankings/trend?shop_id=SHOP_ID&keyword=KEYWORD&from=FROM&to=TO" \
  -H "Authorization: Bearer dk_live_..."
```

## Query parameters

- `shop_id` (string, required) – The shop to inspect
- `keyword` (string, required) – The tracked keyword to follow
- `from` (string, required) (format: date) – First day of the period (UTC)
- `to` (string, required) (format: date) – Last day of the period (UTC)

## Responses

### 200 – Daily ranking series and first/last delta for the keyword

```json
{
  "keyword": "pizza lille",
  "period": {
    "from": "2026-07-01",
    "to": "2026-08-05"
  },
  "days_with_data": 2,
  "first_day": {
    "date": "2026-07-01",
    "average_rank": 8.4
  },
  "last_day": {
    "date": "2026-08-05",
    "average_rank": 4.2
  },
  "rank_delta": -4.2,
  "improved": true,
  "coverage_delta": 27.3,
  "series": [
    {
      "date": "2026-07-01",
      "average_rank": 8.4,
      "center_rank": 5,
      "top3_rate": 18.2,
      "coverage": 72.7,
      "found_points": 8,
      "scanned_points": 11
    },
    {
      "date": "2026-08-05",
      "average_rank": 4.2,
      "center_rank": 2,
      "top3_rate": 45.5,
      "coverage": 100,
      "found_points": 11,
      "scanned_points": 11
    }
  ]
}
```

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