Keyword Suggestion History

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

Name	Type	Required	Default	Description
suggestion	string	Yes	—	Exact autocomplete suggestion
country	string	No	`us`	ISO 3166-1 alpha-2 storefront
days	number	No	`30`	Lookback 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:

Field	Type	Meaning
direction	string	`promoted` (rank improved by ≥ 2), `demoted` (worsened by ≥ 2), `stable`, `fresh` (only one day of data), `unknown` (no observations).
startRank	number \| null	Best rank on the first day of the window.
endRank	number \| null	Best rank on the last observed day.
rankImprovement	number \| null	`startRank − endRank` — positive = improved (lower rank number = higher in dropdown).
newPrefixes	string[]	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.

Getting Started

Apps

Keywords

ASO Tools

Search & Discovery

Market Intelligence

Reference

Query Parameters

Response

`trend`

Data freshness

Credit Cost

Use Cases

​Query Parameters

​Response

​trend

​Data freshness

​Credit Cost

​Use Cases

Query Parameters

Response

`trend`

Data freshness

Credit Cost

Use Cases