---
title: Insights Endpoints
framework: Apple Ads Platform API
role: collectionGroup
role_heading: API Collection
platforms: [apple ads platform api 1.0+]
path: apple-ads-platform-api/insights-endpoints
---

# Insights Endpoints

Query impression share and search term popularity data for your apps.

## Overview

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:  |  |   |  |   |  |  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:  |   |   |   |   |   |   |   |  The options.impressionShareReportType field controls which ad positions the calculation includes:  |   |   |  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:  |   |   |   |   |  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:  |   |   |   |   |

## Topics

- [Impression Share Query](apple-ads-platform-api/query-app-impression-share-data.md)
- [Search Term Popularity Query](apple-ads-platform-api/query-app-search-term-popularity-data.md)

## See Also

### Related Documentation

- [Managing Reports](apple-ads-platform-api/reports.md)
- [Recommendations Endpoints](apple-ads-platform-api/recommendations-endpoints.md)
- [Suggestions Endpoints](apple-ads-platform-api/suggestions-endpoints.md)

### Insights

- [Insights Data Objects](apple-ads-platform-api/insights-data-objects.md)