Impression Share Query
Retrieve impression share data showing how often your ads appear relative to total eligible impressions for a given search term and country.
URL
POST https://api.ads.apple.com/v1/insights/apps/impression-share/queryHeader Parameters
| Name | Type | Description |
|---|---|---|
X-Ap-Context Required | string |
Response Codes
| Status | Reason | Type | Description |
|---|---|---|---|
| 200 | OK Content-Type: application/json | ImpressionShareQueryResponse | Successful response. Returns ImpressionShareQueryResponse ( |
| 400 | Bad Request Content-Type: application/json | Error | Bad Request. Returns Error. |
| 401 | Unauthorized Content-Type: application/json | Error | Unauthorized. |
| 403 | Forbidden Content-Type: application/json | Error | Forbidden. |
| 404 | Not Found Content-Type: application/json | Error | Not Found. Returns Error. |
| 429 | Too Many Requests Content-Type: application/json | Error | Rate Limit Exceeded. Returns Error. |
| 500 | Internal Server Error Content-Type: application/json | Error | Internal Server Error. Returns Error. |
Discussion
This endpoint measures impression share: what fraction of available impressions your app captures for a given search term and country. To identify competitive gaps, use this data. A low impression share on a high-volume term indicates that either budget, bid, or eligibility constraints are limiting your reach.
See Filter for the full set of supported comparison operators.
Filterable Fields
Field | Type | Operators | Description |
|---|---|---|---|
| string |
| Optional. The Adam ID of the promoted app. |
| string |
| Optional. ISO 3166-1 alpha-2 country or region code to scope results to. |
| string (date) |
| Optional. Filter by specific dates. Only usable with |
| string (date) |
| Optional. Filter by week start date. Only usable with |
| string |
| Optional. Display name of the promoted app. |
| string |
| Optional. The search term. |
| number |
| Optional. Lower bound of impression share. |
| number |
| Optional. Upper bound of impression share. |
| integer |
| Optional. App’s impression share rank for the search term and country. |
| integer |
| Optional. Relative search volume on a 1-5 scale. |
Output Types
Configure the output type via options.impressionShareReportType:
Type | Description |
|---|---|
| Measures impression share for the first ad position only. |
| Measures impression share across all ad positions. |
Each row in the response carries the following fields.
Field | Description |
|---|---|
| Date ( |
| Week start date, Sunday ( |
| Display name of the promoted app. |
| Adam ID of the promoted app. |
| ISO 3166-1 alpha-2 country or region code. |
| The search term. Terms with fewer than 10 impressions in the period are suppressed. |
| Lower bound of impression share. See Impression Share Encoding below. |
| Upper bound of impression share. See Impression Share Encoding below. |
| App’s impression share rank for this search term and country. |
| Relative search volume on a 1–5 scale. |
Impression Share Encoding
The lowImpressionShare and highImpressionShare fields use a tiered encoding, not a continuous range:
Impression Share |
|
|
|---|---|---|
0% |
|
|
1% – 90% |
|
|
91% – 100% |
|
|
For single-digit values (1–90%), both fields are equal. When highImpressionShare equals 1, the app has >90% impression share. The encoding preserves the range at that level to avoid false precision near market saturation.
The following limits and defaults apply to this endpoint’s requests and responses.
Constraint | Detail |
|---|---|
Timezone | Fixed to |
Granularity | Supports |
| 30 days (inclusive). |
| 4 weeks. |
Weekly start date | When |
Default | 100. |
Maximum | 10000. |
Sort fields | Maximum 2 sort fields per request. |
High-saturation bucket |
|
Privacy filter | The privacy filter suppresses |
Estimate Market Size
To estimate total eligible inventory for a search term, use impression share alongside confirmed impressions:
estimated_market_impressions ≈ confirmed_impressions / lowImpressionShare
Example: 10,000 confirmed impressions at lowImpressionShare: 0.04 (4%) → ≈ 250,000 total eligible impressions. The same app at lowImpressionShare: 0.91 (>90% bucket) has captured nearly all available inventory. Single-digit precision makes this estimate meaningful across the 1–90% range covered by lowImpressionShare. Only within the 91–100% bucket, where lowImpressionShare and highImpressionShare diverge to 0.91 and 1.0, does the estimate lose that precision.