Get Keyword Serp
get_keyword_serpThe App Store search results for one term in one storefront, on one day: who ranked, in what order, with their names, subtitles and ratings. This is how you find out WHO took the places an app lost — a rank that fell is a fact, and the results page on the day it fell is the reason. Works for ANY term in the store, tracked or not, known to us or not: pass keyword_id for a term you already have an id for, or keyword + country for words a user typed, which resolves the term and crawls the storefront live when what we hold is over a day old. Omit the date for the most recent crawl. A lookup can persist a new shared keyword record and queue a background crawl that updates stored search observations. It does not track the keyword for your account.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| date | No | The day to read, `YYYY-MM-DD`. Omit for the most recent crawl, which is the only mode that ever crawls live — naming a day is a question about the past and is answered from what was recorded. A day nobody crawled comes back empty with `crawled: false` rather than as an error; pick one from `crawled_days`, which the answer always returns. | |
| limit | No | How deep to read. Default 25, capped at 50. Below about 25 nobody is competing with you for the term. | |
| country | No | Storefront for `keyword`, e.g. "us", "jp". Required with `keyword` and ignored with `keyword_id`, because a keyword already names its storefront. There is no worldwide search results page — every App Store search happens in one country. | |
| keyword | No | The search term itself, for words a user typed rather than an id — "sleep tracker", "заметки". Needs `country`. A term nobody has ever looked up is created and the storefront is read live, so this answers for any search in the store and not only for terms Apptail already holds. Prefer `keyword_id` when you have one: it is the exact row, where words go through the store's own normalisation first. | |
| keyword_id | No | Apptail keyword id — from get_keywords or discover_keywords, or off a `rank.move` signal. The storefront is fixed by the keyword itself; a term is tracked per country. Give this OR `keyword` + `country`, not both. |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| apps | Yes | The results in rank order, best first. `is_mine` marks the account's own apps and `is_tracked_competitor` marks rivals it already watches — a high-ranking app that is neither is worth suggesting they add. | |
| date | No | The day actually read, which is the day asked for or the most recent crawl. Null when nothing has been crawled for this term. | |
| count | Yes | Apps returned. | |
| country | No | Storefront these results come from. Fixed by the keyword. | |
| crawled | Yes | Whether that day had a crawl at all. False with an empty list means nobody measured, **not** that nobody ranked. | |
| keyword | Yes | The search term itself. | |
| refreshed | Yes | True when this call read the App Store rather than the database — a term looked up for the first time, or one whose last crawl was over a day old. False means these are stored results; `date` says which day they are from. Do not describe results as live unless this is true. | |
| keyword_id | Yes | The term that was read. | |
| popularity | No | Apple search popularity for the term, roughly 5-100. Higher means more searched. Read it before calling a position valuable. | |
| console_url | No | Where this search is shown in the console, with the icons and screenshots this payload leaves out. | |
| my_position | No | The best rank held here by one of the account's own apps, or null when none of them are in these results. Null is not -1: it means no app of theirs appears in the depth that was read, which is not the same as being measured and absent. | |
| crawled_days | Yes | Days in the last 30 that were crawled, newest first. Name one in `date` to see how the results looked then — comparing two days is what shows who took a place. | |
| results_count | No | How many apps the store returns for this term in total. The results below are the top of that. |