Skip to main content
GET /v1/keywords/suggestions/history
For one suggestion (e.g. "ai chat"), returns the per-day record of every prefix that surfaced it in Apple’s autocomplete, plus the best rank Apple placed it in. Use this to confirm whether a suggestion is sticky or a one-day flicker, and to understand which prefix paths users follow to discover it.

​
Query Parameters

NameTypeRequiredDefaultDescription
suggestionstringYes—Exact autocomplete suggestion
countrystringNousISO 3166-1 alpha-2 storefront
daysnumberNo30Lookback window in days, 3–180

​
Response

{
  "data": {
    "suggestion": "ai chat",
    "country": "us",
    "windowDays": 30,
    "firstSeen": "2026-04-04",
    "lastSeen": "2026-04-21",
    "isCurrentlyVisible": true,
    "series": [
      { "date": "2026-04-04", "bestRank": 9, "prefixes": ["a", "ai"], "appearances": 2 },
      { "date": "2026-04-05", "bestRank": 7, "prefixes": ["a", "ai", "ai "], "appearances": 3 },
      { "date": "2026-04-21", "bestRank": 3, "prefixes": ["a", "ai", "ai c"], "appearances": 4 }
    ],
    "trend": {
      "direction": "promoted",
      "startRank": 9,
      "endRank": 3,
      "rankImprovement": 6,
      "newPrefixes": ["ai c"]
    },
    "interpretation": "Apple promoted 'ai chat' from rank 9 to rank 3 — strong demand signal. New prefix coverage: ai c."
  },
  "meta": {
    "lastScrapedAt": "2026-04-21T00:00:00Z",
    "dataAgeHours": 4,
    "source": "stored",
    "freshness": "fresh"
  }
}
isCurrentlyVisible is true when the suggestion appeared in today’s snapshot — a quick way to confirm whether the trend is still live before acting on it.

​
trend

Window-over-window read of how Apple’s perception of the suggestion is moving:
FieldTypeMeaning
directionstringpromoted (rank improved by ≥ 2), demoted (worsened by ≥ 2), stable, fresh (only one day of data), unknown (no observations).
startRanknumber | nullBest rank on the first day of the window.
endRanknumber | nullBest rank on the last observed day.
rankImprovementnumber | nullstartRank − endRank — positive = improved (lower rank number = higher in dropdown).
newPrefixesstring[]Prefixes seen in the most recent 7 days that weren’t seen earlier in the window — Apple expanding the suggestion into new prefix neighbourhoods is the strongest possible “demand rising” signal we can see.
interpretation is a one-line plain-English summary of the trend — safe to surface directly in a UI and useful for LLM agents. The response-level meta envelope describes data freshness — see Keyword Metrics → meta envelope for the schema.

​
Data freshness

The suggestion archive is refreshed daily per storefront, so the response reflects the most recent overnight snapshot. Use the response-level meta envelope above to read the exact lastScrapedAt and freshness band for each call.

​
Credit Cost

2 credits per request.

​
Use Cases

  • Decide whether to invest in ranking for a suggestion based on its history (sticky vs one-off).
  • Detect when a previously-strong suggestion stops being surfaced (signal of changing search behaviour).
  • Build a “discovery path” view: which prefixes users type to reach the suggestion.