Insights

Overview

Insights reports show how users interact with locations in Apple Maps, including search engagement, Apple Maps place card views, and Apple Maps place card actions.

For a general description, see Insights.

Insights Metrics

Insights metrics include:

• Taps on locations in search results.

• Apple Maps place card taps on action row buttons like directions, call, website, shares, and action links.

For a complete list of available metrics, see Business API > Insights > Quick Report > Request > Request Body values. The downloadable csv file offers a list of reporting options, most of which are direct Apple Maps place card actions.

Insights Reports

• Quick report – synchronous call for fetching small amounts of data. It returns data based on current resource states. For example, it can be used to receive incremental updates of the most recent metrics for a location. See Business API > Insights > Quick Report.

• Request report – is an asynchronous call and is more appropriate for receiving larger outputs, such as backfilling the historical usage metrics for a location. See Business API > Insights > Request Report.

Insights Reports Considerations

Privacy Data Threshold

To protect the identities of individual users, metrics reporting below a threshold are represented as zero. We recommend requesting daily, weekly, and monthly intervals (rather than summing daily data). Longer aggregation periods are more likely to exceed the privacy threshold.

Maximum Requested Reports

Insights API allows each partner to create a maximum of 100,000 asynchronously generated reports. Do not use the Apple Business system to store reports long term. Use the report buffer for temporary storage to hold the reports only until you can download them.

This limit is not applied to the number of requests.

See Generate Reports Asynchronously.

Combine Calls

Optimize API usage by pulling multiple metrics with a single request using PLACECARD_SEARCH_COMBINED.

Showcase Metrics

Request showcase metrics at the location level (resourceId = Apple-generated location ID and resourceType = LOCATION) or at the showcase level (resourceId = Apple-generated showcase ID and resourceType = SHOWCASE).

Metrics reported by showcase ID allow the partner to associate the engagement with showcase attributes, such as startDate and endDate, and SHOWCASE-CREATIVE details such as callToAction.

Historical Backfill

If you want to backfill the full history of available data, notify Apple Business so we can provide guidance on scheduling these requests. Use the asynchronous Request Report API for historical backfills and not Quick Report API.

After historical data is backfilled, regularly pull more current metrics for locations using the Quick Report.

Generate Reports Asynchronously

A typical call sequence to request metrics for delegated locations:

1. Request report for N number of locations.

   Make separate call for each delegated location. Where N is the total number of Queries per Second (QPS) allowed. For example, if QPS is 20, submit requests for 20 locations. See Business API > Insights > Request Report.

2. Check for report completion.

   Fetch reports which are state=COMPLETED. Response lists report IDs that are completed. See Business API > Insights > Get.

3. Request and save a report for each location.

   Using a report's ID, fetch the metrics for each location. See Business API > Insights > Get by ID.

4. Delete the report.

   Once the report is saved, delete the report. Too avoid TOO_MANY_REPORTS error code, keep the number of reports stored in Apple Business below the maximum number of 100,000. See Business API > Insights > Delete Report.

Figure: Sequence of Insights Calls

API Call Sequence

On average, the time to complete a report request is 2-3 seconds. Actual time depends on system load.

Staggering and overlapping Request Report API calls and subsequent Get API calls to gather the metrics data decreases the overall time to process 100's or 1000's of locations.

The table lists QPS used and the clock time for each call in the Request Report for location metrics sequence. In this example, the maximum QPS is 20.

Step	Clock Time	Call	No. of Queries
T0	9:00:00	Request Report (by location ID x N)	20
T1	9:00:01	Get reports (state=COMPLETED)	1
T2	9:00:02	Get by ID (by report ID)	20
T3	9:00:03	Delete (by report ID)	1
T4	9:00:04	Request Report (by report ID x N)	20