Insights Endpoints
Query impression share and search term popularity data for your apps.
Overview
To look deeply into performance across your campaign group and identify growth opportunities, use the search term popularity and impression share APIs. Both endpoints apply only to App Store app campaigns (promotedObjectType APPSTORE_APP). Apple Maps (BUSINESS_BRAND) campaigns have no Insights equivalent.
Query the Available Endpoints
Query the following endpoints to retrieve insights data:
Method | Path | Description |
|---|---|---|
|
| Retrieves impression share data for the specified keywords and time range. See Query App Impression Share Data. |
|
| Retrieves search term popularity rankings by App Store country or region and genre. See Query App Search Term Popularity Data. |
Measure Impression Share
Impression share reports measure your share of available impressions relative to competitors for a given set of keywords or app categories. The report shows how often your ad appeared in any ad position for a specific search term, out of the total number of searches on that search term, in the same App Store country or region. Use impression share data to understand how competitive you are on a given search term and how much headroom exists to increase reach.
To retrieve impression share data, use POST /v1/insights/apps/impression-share/query (Impression Share Query). You must filter on promotedObjectId, or the request fails with a 400 error. The endpoint returns results synchronously with pagination. The following table lists the granularity options and limits for impression share queries:
Field | Details |
|---|---|
Granularity |
|
| 30 days (inclusive) |
| 4 weeks |
Weekly start date | When |
Timezone | Fixed to UTC |
Maximum pageSize | 10000 |
Maximum sort fields | 2 |
The options.impressionShareReportType field controls which ad positions the calculation includes:
Report Type | Description |
|---|---|
| Measures impression share for the first ad position only. |
| Measures impression share aggregated across all ad positions. |
The lowImpressionShare and highImpressionShare fields use single-digit precision for values from 1–90% (both fields are equal). For values above 90%, both fields encode the 91–100% bucket (0.91 / 1.0) to avoid false precision near market saturation.
Each row also returns rank (the app’s stack-ranked position by impression share for that search term and country, 1 = highest) and searchPopularity1to5 (relative search volume for the term, 5 = most popular).
Discover Search Term Popularity
Search term popularity reports show the relative ranking of search terms by volume within a given App Store country or region and genre. Use search term popularity data to discover high-volume search terms, understand seasonal trends, and prioritize keyword additions.
Use monthly and weekly search term popularity data to understand search volume trends and identify high-opportunity terms.
To retrieve search term popularity data, use POST /v1/insights/apps/search-term-popularity/query (Search Term Popularity Query). This endpoint always uses UTC. The following table lists the granularity options and limits for search term popularity queries:
Field | Details |
|---|---|
Granularity |
|
Timezone | Fixed to UTC |
Maximum pageSize | 10000 |
Maximum sort fields | 2 (default: |
The response always returns all dimension fields: countryOrRegion, genre, searchTerm, and the date field for the selected granularity (week or month). Request additional fields via the fields array:
Optional Field | Description |
|---|---|
| The search term’s rank by volume within the genre. |
| Relative popularity score within the genre, on a 1–100 scale. |
| Popularity score on a 1–100 scale across all genres within the country or region. |
| Simplified popularity tier on a 1–5 scale. |