Public Apple Search Ads API Reference

The public API procedures may call the internal procedures which should not be used directly as they can be changed without any explicit notification in the newer versions of the connector. Internal procedures can be recognized by the prefix internal_ in their names. Public API procedures do not have such prefix in their names.

ACLs

User Access Control List (ACL)
Parameter
<preview> (optional): Preview only, don't write into table
<target_table> (optional): Table name to save the data to
<label> (optional): Multi-tenancy label

Example

CREATE VIEW apple_search_ads_examples.example_ACLs AS 
	SELECT * 
	FROM (
		CALL apple_search_ads.ACLs ()
	) AS x

AdGroups

Ad groups by using a campaign identifier
Parameter
<campaignId> (optional): The identifier for the campaign. When you create a campaign, the system sets the Id
<adgroupId> (optional): The identifier for the ad group. When you create an ad group, the system sets the Id based on the campaignId in the URI
<conditions> (optional): A list of condition objects which allows users to filter a list of records
<orgId> (optional): Organization ID
<campaign_table> (optional): Table with campaign info. Campign id must be named as id
<preview> (optional): Preview only, don't write into table
<target_table> (optional): Table name to save the data to
<label> (optional): Multi-tenancy label

Example

CREATE VIEW apple_search_ads_examples.example_AdGroups AS 
	SELECT * 
	FROM (
		CALL apple_search_ads.AdGroups (
			campaignId => 489025549
		)
	) AS x

AdGroupsCreativeSets

Creative Sets assigned to ad groups
Parameter
<conditions> (optional): A list of condition objects which allows users to filter a list of records
<campaignId> (optional): The unique identifier for the campaign. When you create a campaign, the system sets the Id
<orgId> (optional): Organization ID
<campaign_table> (optional): Table with campaign info. Campign id must be named as id
<preview> (optional): Preview only, don't write into table
<target_table> (optional): Table name to save the data to
<label> (optional): Multi-tenancy label

Example

CREATE VIEW apple_search_ads_examples.example_AdGroupsCreativeSets AS 
	SELECT * 
	FROM (
		CALL apple_search_ads.AdGroupsCreativeSets (
			campaignId => 474938929,
			conditions => NULL
		)
	) AS x

AdGroupsNegativeKeywords

Negative keywords used in a campaign
Parameter
<campaignId> (optional): The unique identifier for the campaign. When you create a campaign, the system sets the Id
<adgroupId> (optional): The unique identifier for the ad group. When you create an ad group, the system sets the Id based on the campaignId in the URI
<keywordId> (optional): The unique identifier for the keyword. When you create campaign negative keywords, the system sets the Id based on the campaignId in the URI
<conditions> (optional): A list of condition objects which allows users to filter a list of records
<orgId> (optional): Organization ID
<campaign_adgroup_table> (optional): Table with campaigns and adgroups info. Campaign id must be named as campaignId and adgroup id must be named as adgroupId
<preview> (optional): Preview only, don't write into table
<target_table> (optional): Table name to save the data to
<label> (optional): Multi-tenancy label

Example

CREATE VIEW apple_search_ads_examples.example_AdGroupsNegativeKeywords AS 
	SELECT * 
	FROM (
		CALL apple_search_ads.AdGroupsNegativeKeywords (
			adgroupId => 474985334,
			campaignId => 474938929
		)
	) AS x

AdGroupsTargetingKeywords

Targeting keywords used in ad groups
Parameter
<campaignId> (optional): The unique identifier for the campaign. When you create a campaign, the system sets the Id
<adgroupId> (optional): The unique identifier for the ad group. When you create an ad group, the system sets the Id based on the campaignId in the URI
<keywordId> (optional): The unique identifier for the keyword. When you create ad group targeting keywords, the system sets the Id based on the campaignId and adgroupId in the URI
<conditions> (optional): A list of condition objects which allows users to filter a list of records
<orgId> (optional): Organization ID
<campaign_adgroup_table> (optional): Table with campaigns and adgroups info. Campaign id must be named as campaignId and adgroup id must be named as adgroupId
<preview> (optional): Preview only, don't write into table
<target_table> (optional): Table name to save the data to
<label> (optional): Multi-tenancy label

Example

CREATE VIEW apple_search_ads_examples.example_AdGroupsTargetingKeywords AS 
	SELECT * 
	FROM (
		CALL apple_search_ads.AdGroupsTargetingKeywords (
			campaignId => 193716434,
			adgroupId => 193778218
		)
	) AS x

BudgetOrders

Budget orders assigned to an org
Parameter
<orgId> (optional): Organization ID
<boId> (optional): The unique identifier for the budget order. When creating a budget order through the Apple Search Ads UI, a budget order Id (boId) is set
<preview> (optional): Preview only, don't write into table
<target_table> (optional): Table name to save the data to
<label> (optional): Multi-tenancy label

Example

CREATE VIEW apple_search_ads_examples.example_BudgetOrders AS 
	SELECT * 
	FROM (
		CALL apple_search_ads.BudgetOrders ()
	) AS x

Campaigns

Campaigns assigned to an org
Parameter
<campaignId> (optional): The unique identifier for the campaign. When you create a campaign, the system sets the Id
<conditions> (optional): A list of condition objects which allows users to filter a list of records
<orgId> (optional): Organization ID
<preview> (optional): Preview only, don't write into table
<target_table> (optional): Table name to save the data to
<label> (optional): Multi-tenancy label

Example

CREATE VIEW apple_search_ads_examples.example_Campaigns AS 
	SELECT * 
	FROM (
		CALL apple_search_ads.Campaigns ()
	) AS x

CampaignsNegativeKeywords

Negative keywords used in a campaign
Parameter
<campaignId> (optional): The unique identifier for the campaign. When you create a campaign, the system sets the Id
<keywordId> (optional): The unique identifier for the keyword. When you create campaign negative keywords, the system sets the Id based on the campaignId in the URI
<conditions> (optional): A list of condition objects which allows users to filter a list of records
<orgId> (optional): Organization ID
<campaign_table> (optional): Table with campaign info. Campign id must be named as id
<preview> (optional): Preview only, don't write into table
<target_table> (optional): Table name to save the data to
<label> (optional): Multi-tenancy label

Example

CREATE VIEW apple_search_ads_examples.example_CampaignsNegativeKeywords AS 
	SELECT * 
	FROM (
		CALL apple_search_ads.CampaignsNegativeKeywords (
			campaignId => 491869233
		)
	) AS x

CreativeAppAssets

Assets used with Creative Sets
Parameter
<adamId> (optional): Use your adamId in the URI.Your unique iTunes application identifier. Each time you use an adamId in the API, it must match the adamId used in your campaign
<assetsGenIds> (optional): The relationship between a Creative Set and an asset
<countryOrRegions> (required): The App Store territory you are promoting your app. The default is US
<adamId_table> (optional): Table with campaign info. Adam id must be named as adamId
<orgId> (optional): Organization ID
<preview> (optional): Preview only, don't write into table
<target_table> (optional): Table name to save the data to
<label> (optional): Multi-tenancy label

Example

CREATE VIEW apple_search_ads_examples.example_CreativeAppAssets AS 
	SELECT * 
	FROM (
		CALL apple_search_ads.CreativeAppAssets (
			adamId => 602283488,
			countryOrRegions => 'US,DE',
			assetsGenIds => NULL
		)
	) AS x

CreativeSets

Creative Sets assigned to an organization
Parameter
<creativeSetId> (optional): The unique identifier for the Creative Set. When you create a Creative Set, the system sets the Id
<conditions> (optional): A list of condition objects which allows users to filter a list of records
<orgId> (optional): Organization ID
<preview> (optional): Preview only, don't write into table
<target_table> (optional): Table name to save the data to
<label> (optional): Multi-tenancy label

Devices

Supported app preview device size mappings
Parameter
<orgId> (optional): Organization ID
<preview> (optional): Preview only, don't write into table
<target_table> (optional): Table name to save the data to
<label> (optional): Multi-tenancy label

Example

CREATE VIEW apple_search_ads_examples.example_Devices AS 
	SELECT * 
	FROM (
		CALL apple_search_ads.Devices ()
	) AS x

GeoLocations

Geo locations used for audience refinement
Parameter
<countrycode> (optional): The country in which to serve ads. Note, geo targeting is not supported for campaigns served to multiple countries or regions. The query uses a countrycode value in ISO-ALPHA2-COUNTRYCODE format. Use Search for iOS Apps to retrieve countryOrRegionCodes
<entity> (optional): The country, adminArea, or Locality locations available for targeting. A countrycode is a mandatory parameter. AdminArea is the state or the equivalent according to its associated Country. Locality is the city or the equivalent according to its associated AdminArea
<query> (optional): The query search pattern uses a prefix-matching algorithm. Spaces are allowed in search patterns. Prefixes require a minimum of three characters
<orgId> (optional): Organization ID
<preview> (optional): Preview only, don't write into table
<target_table> (optional): Table name to save the data to
<label> (optional): Multi-tenancy label

Example

CREATE VIEW apple_search_ads_examples.example_GeoLocations AS 
	SELECT * 
	FROM (
		CALL apple_search_ads.GeoLocations (
			countrycode => 'DE',
			entity => NULL,
			query => NULL
		)
	) AS x

IOSApps

Searches for iOS apps to promote in a campaign
Parameter
<query> (required): The query for a list of iOS apps using a matching prefix.The query search pattern uses a prefix-matching algorithm
<orgId> (optional): Organization ID
<preview> (optional): Preview only, don't write into table
<target_table> (optional): Table name to save the data to
<label> (optional): Multi-tenancy label

Example

CREATE VIEW apple_search_ads_examples.example_IOSApps AS 
	SELECT * 
	FROM (
		CALL apple_search_ads.IOSApps (
			query => 'Run K'
		)
	) AS x

ReportsAdGroups

Reports on ad groups within a campaign
Parameter
<startTime> (required): The date the report coverage starts
<endTime> (optional): The date the report coverage ends
<granularity> (required): The report data organized by hour, day, week, and month. Possible values: MONTHLY, WEEKLY, DAILY, HOURLY
<campaignId> (optional): The identifier for the campaign. The Id is set when a campaign is created
<conditions> (optional): A list of condition objects which allows users to filter a list of records
<returnRecordsWithNoMetrics> (optional): The parameter used to specify whether records with no stats should also be returned. The default is false
<timeZone> (optional): The default timeZone is set during account creation through the Search Ads UI. ORTZ (Org time zone) is the default timezone. Possible values: UTC, ORTZ
<orgId> (optional): Organization ID
<campaign_table> (optional): Table with campaign info. Campign id must be named as id
<preview> (optional): Preview only, don't write into table
<target_table> (optional): Table name to save the data to
<label> (optional): Multi-tenancy label

Example

CREATE VIEW apple_search_ads_examples.example_ReportsAdGroups AS 
	SELECT * 
	FROM (
		CALL apple_search_ads.ReportsAdGroups (
			campaignId => 220668802,
			startTime => TIMESTAMPADD (SQL_TSI_DAY, -30, CURDATE ()),
			endTime => CURDATE (),
			timeZone => 'ORTZ',
			granularity => 'DAILY',
			returnRecordsWithNoMetrics => NULL,
			conditions => NULL
		)
	) AS x

ReportsCampaigns

Reports on campaigns
Parameter
<startTime> (required): The date the report coverage starts
<endTime> (optional): The date the report coverage ends
<granularity> (required): The report data organized by hour, day, week, and month. Possible values: MONTHLY, WEEKLY, DAILY, HOURLY
<conditions> (optional): A list of condition objects which allows users to filter a list of records
<returnRecordsWithNoMetrics> (optional): The parameter used to specify whether records with no stats should also be returned. The default is false
<timeZone> (optional): The default timeZone is set during account creation through the Search Ads UI. ORTZ (Org time zone) is the default timezone. Possible values: UTC, ORTZ
<orgId> (optional): Organization ID
<preview> (optional): Preview only, don't write into table
<target_table> (optional): Table name to save the data to
<label> (optional): Multi-tenancy label

Example

CREATE VIEW apple_search_ads_examples.example_ReportsCampaigns AS 
	SELECT * 
	FROM (
		CALL apple_search_ads.ReportsCampaigns (
			startTime => TIMESTAMPADD (SQL_TSI_DAY, -30, CURDATE ()),
			endTime => CURDATE (),
			timeZone => 'ORTZ',
			granularity => 'DAILY',
			returnRecordsWithNoMetrics => NULL,
			conditions => NULL
		)
	) AS x

ReportsCreativeSets

Reports on Creative Sets used within a campaign
Parameter
<startTime> (required): The date the report coverage starts
<endTime> (optional): The date the report coverage ends
<granularity> (required): The report data organized by hour, day, week, and month. Possible values: MONTHLY, WEEKLY, DAILY
<campaignId> (optional): The identifier for the campaign. The Id is set when a campaign is created
<conditions> (optional): A list of condition objects which allows users to filter a list of records
<returnRecordsWithNoMetrics> (optional): The parameter used to specify whether records with no stats should also be returned. The default is false
<timeZone> (optional): The default timeZone is set during account creation through the Search Ads UI. ORTZ (Org time zone) is the default timezone. Possible values: UTC, ORTZ
<orgId> (optional): Organization ID
<campaign_table> (optional): Table with campaign info. Campign id must be named as id
<preview> (optional): Preview only, don't write into table
<target_table> (optional): Table name to save the data to
<label> (optional): Multi-tenancy label

Example

CREATE VIEW apple_search_ads_examples.example_ReportsCreativeSets AS 
	SELECT * 
	FROM (
		CALL apple_search_ads.ReportsCreativeSets (
			campaignId => 491869233,
			startTime => TIMESTAMPADD (SQL_TSI_DAY, -30, CURDATE ()),
			endTime => CURDATE (),
			timeZone => 'ORTZ',
			granularity => 'DAILY',
			returnRecordsWithNoMetrics => NULL,
			conditions => NULL
		)
	) AS x

ReportsKeywords

Reports on targeting keywords within a campaign
Parameter
<startTime> (required): The date the report coverage starts
<endTime> (optional): The date the report coverage ends
<granularity> (required): The report data organized by hour, day, week, and month. Possible values: MONTHLY, WEEKLY, DAILY, HOURLY
<campaignId> (optional): The identifier for the campaign. The Id is set when a campaign is created
<conditions> (optional): A list of condition objects which allows users to filter a list of records
<returnRecordsWithNoMetrics> (optional): The parameter used to specify whether records with no stats should also be returned. The default is false
<timeZone> (optional): The default timeZone is set during account creation through the Search Ads UI. ORTZ (Org time zone) is the default timezone. Possible values: UTC, ORTZ
<orgId> (optional): Organization ID
<campaign_table> (optional): Table with campaign info. Campign id must be named as id
<preview> (optional): Preview only, don't write into table
<target_table> (optional): Table name to save the data to
<label> (optional): Multi-tenancy label

Example

CREATE VIEW apple_search_ads_examples.example_ReportsKeywords AS 
	SELECT * 
	FROM (
		CALL apple_search_ads.ReportsKeywords (
			campaignId => 491869233,
			startTime => TIMESTAMPADD (SQL_TSI_DAY, -30, CURDATE ()),
			endTime => CURDATE (),
			timeZone => 'ORTZ',
			granularity => 'DAILY',
			returnRecordsWithNoMetrics => NULL,
			conditions => NULL
		)
	) AS x

ReportsSearchTerms

Reports on search terms used in a campaign
Parameter
<startTime> (required): The date the report coverage starts
<endTime> (optional): The date the report coverage ends
<granularity> (required): The report data organized by hour, day, week, and month. Possible values: MONTHLY, WEEKLY, DAILY
<campaignId> (optional): The identifier for the campaign. The Id is set when a campaign is created
<conditions> (optional): A list of condition objects which allows users to filter a list of records
<returnRecordsWithNoMetrics> (optional): The parameter used to specify whether records with no stats should also be returned. The default is false
<timeZone> (optional): The default timeZone is set during account creation through the Search Ads UI. ORTZ (Org time zone) is the default timezone. Possible values: UTC, ORTZ
<orgId> (optional): Organization ID
<campaign_table> (optional): Table with campaign info. Campign id must be named as id
<preview> (optional): Preview only, don't write into table
<target_table> (optional): Table name to save the data to
<label> (optional): Multi-tenancy label

Example

CREATE VIEW apple_search_ads_examples.example_ReportsSearchTerms AS 
	SELECT * 
	FROM (
		CALL apple_search_ads.ReportsSearchTerms (
			campaignId => 491869233,
			startTime => TIMESTAMPADD (SQL_TSI_DAY, -30, CURDATE ()),
			endTime => CURDATE (),
			timeZone => 'ORTZ',
			granularity => 'DAILY',
			returnRecordsWithNoMetrics => false,
			conditions => NULL
		)
	) AS x