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


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


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