Apple Search Ads

Last updated on Jul 03, 2025
On This Page

From Release 2.32.2, Hevo has upgraded to v5.0 of the Campaign Management API to fetch your data. This new API version includes two new fields, suggested_bid_amount and suggested_bid_currency, in the Keyword Report object.

If you need historical data for the new fields in your existing Pipelines, you must restart the historical load for the Keyword Report object. This change applies to all new and existing Pipelines.

Apple Search Ads are sponsored ads for driving awareness and downloads for apps within Apple’s App Store. This allows you to promote your applications at the top of the search results on the App Store.

You can use Hevo Pipelines to replicate your Apple Search Ads reports such as campaign reports and search term reports into the desired Destination system for scalable analysis. For this, you must authorize Hevo to access data from your Apple Search Ads account using the API keys.

You must use your Apple Search Account credentials to authenticate the account with Hevo for all Pipelines created after Release 1.87. The credentials are a combination of a public key and a private key.

Note: The certificate based authentication has been completely deprecated.

Prerequisites

  • The user account has either API Account Read-only or API Account Manager access. This can be provided by your Apple Search Ads admin.

    user roles

  • The user account has access to at least one application hosted on the App Store.

  • You are assigned the Team Administrator, Team Collaborator, or Pipeline Administrator role in Hevo to create the Pipeline.

Obtaining your Apple Search Ads Credentials

You require Apple Search Ads credentials (client ID, team ID, and key ID) to authenticate Hevo on your Apple Search Ads account. These credentials do not expire and can be reused for all your Pipelines.

Note: You must log in as a user with API Account Read-only or API Account Manager access to perform these steps.

To obtain these credentials:

  1. Copy the Public Key from the Source configuration page in Hevo. Refer to section, Configuring Apple Search Ads as a Source to find the key.

    public-key-page

  2. Log in to your Apple Search Ads account.

  3. In the top right corner of the page, click on your username and click Settings.

    click-username-and-settings

  4. On the Account Settings page, API tab, Client Credentials section, do one of the following:

    • Generate the credentials:

      1. Paste the Public Key that you copied from the Hevo UI and click Generate API Client.

        generate-api-client

      2. Copy the generated clientId, teamId, and keyId.

        copy-generated-credentials

    • Use existing credentials:

      1. Copy the clientId, teamId, and keyId values.

        copy-existing-credentials

You can use these credentials while configuring your Hevo Pipeline.

Configuring Apple Search Ads as a Source

Perform the following steps to configure Apple Search Ads as the Source in your Pipeline:

  1. Click PIPELINES in the Navigation Bar.

  2. Click + CREATE PIPELINE in the Pipelines List View.

  3. On the Select Source Type page, select Apple Search Ads.

  4. On the Configure your Apple Search Ads Source page, specify the following:

    configure-source-page

    • Pipeline Name: A unique name for your Pipeline, not exceeding 255 characters.

    • Public Key (Non-editable): The public key that you used to obtain the Apple Search Ads credentials. This value is pre-filled.

    • Client ID: The client ID that you obtained from your Apple Search Ads account.

    • Team ID: The team ID that you obtained from your Apple Search Ads account.

    • Key ID: The key ID that you obtained from your Apple Search Ads account.

    • Organizations: One or more organizations from which you want to ingest the data.

    • Historical Sync Duration: The duration for which you want to ingest the existing data from the Source. Default duration: 1 Year.

      Note: If you select All Available Data, Hevo ingests all the data available in your Apple Search Ads account since June 15, 2016.

  5. Click TEST & CONTINUE.

  6. Proceed to configuring the data ingestion and setting up the Destination.

Data Replication

For Teams Created Default Ingestion Frequency Minimum Ingestion Frequency Maximum Ingestion Frequency Custom Frequency Range (in Hrs)
Before Release 2.21 6 Hrs 1 Hr 24 Hrs 1-24
After Release 2.21 6 Hrs 30 Mins 24 Hrs 1-24

Note: The custom frequency must be set in hours as an integer value. For example, 1, 2, or 3, but not 1.5 or 1.75.

  • Historical Data: The first run of the Pipeline ingests historical data for the selected objects on the basis of the historical sync duration specified at the time of creating the Pipeline and loads it to the Destination. Default duration: 1 Year.

  • Incremental Data: Once the historical load is complete, data is ingested as per the ingestion frequency in Full Load or Incremental mode, as applicable.

  • Refresh: Hevo refreshes the data for all the objects on a rolling basis to update any conversions attributed to clicks within the last 30 days.

Schema and Primary Keys

Hevo uses the following schema to upload the records in the Destination:

Data Model

The following tables (objects) are created in the Destination when you run the Pipeline.

Note: In Pipelines created from Release 1.87 onwards, Hevo also loads the country_or_region field for all the object reports. If you need this field in an existing Pipeline, you need to recreate the Pipeline.

Table Description
Ad Group Contains the ad group entities associated with a campaign, and the ad group for each campaign group.
Ad Group Report Contains the daily report of each ad group.
Ad Level Report Contains the ad performance data associated with a campaign.
Campaign Group Contains the campaign groups and the Access Control List (ACL) of the authenticated Apple Search Ads account.
Campaign Contains the details of the campaigns assigned to a campaign group.
Campaign Report Contains the daily report of each searched campaign.
Creative Set Report Contains the daily report of creative sets used in your campaign.
Custom Product Pages Contains the details of the custom product pages.
Keyword Report Contains the daily report of each keyword associated with an Ad Group.
Impression Share Reports Contains details about how frequently your ads appear in the app store search results in comparison to their competitors’ ads.
Search Terms Report Contains the daily report of search terms used in the App Store.
Targeting Keyword Contains the details of the targeting keywords associated with each ad group. Targeting keywords display ads based on the relevant search terms used.

Additional Information

Read the detailed Hevo documentation for the following related topics:

Source Considerations

  • Apple Search Ads API users can authenticate using only the API keys. Even if an existing certificate is still valid, you need to recreate the Pipeline using the API Keys. This is because Apple Search Ads has deprecated certificate based authentication.

  • For Impression Share Reports, you can generate a maximum of 10 reports per day and select a date range of up to 30 days for any time period after April 12th, 2020.

Limitations

  • Hevo does not load data from a column into the Destination table if its size exceeds 16 MB, and skips the Event if it exceeds 40 MB. If the Event contains a column larger than 16 MB, Hevo attempts to load the Event after dropping that column’s data. However, if the Event size still exceeds 40 MB, then the Event is also dropped. As a result, you may see discrepancies between your Source and Destination data. To avoid such a scenario, ensure that each Event contains less than 40 MB of data.

Revision History

Refer to the following table for the list of key updates made to this page:

Date Release Description of Change
Jul-07-2025 NA Updated the Limitations section to inform about the max record and column size in an Event.
Feb-03-2025 2.32.2 Updated the page overview to add a warning container to inform about the upgrade to Campaign Management API v5.0.
Jan-07-2025 NA Added a limitation about Event size.
Mar-05-2024 2.21 Updated the ingestion frequency table in the Data Replication section.
Oct-03-2023 NA Updated section, Obtaining your Apple Search Ads Credentials to reflect the latest Apple Search Ads UI.
May-30-2023 2.13 Updated sections, Data Model with the latest list of objects and their respective descriptions.
Apr-04-2023 NA Updated section, Configuring Apple Search Ads as a Source to update the information about historical sync duration.
Dec-07-2022 NA Updated section, Data Replication to reorganize the content for better understanding and coherence.
Apr-25-2022 1.87 - Removed section, Authorize Hevo Using an API Certificate and structured the existing content accordingly.
- Updated sections, Schema and Primary Keys and Data Model with the latest list of objects and their respective descriptions.
- Added section, Source Considerations.
Apr-11-2022 1.86 Updated sections, Schema and Primary Keys and Data Model with the information relating to the support for the country_or_region field.
Oct-25-2021 NA Added the Pipeline frequency information in the Data Replication section.
Aug-05-2021 1.68 - Added section, Authorizing Hevo Using API Keys
- Updated section, Configuring Apple Search Ads as a Source with steps to configure the Source using API Key credentials.
Was this page helpful?

Tell us what went wrong