| Title: | Get Data from 'Apple Ads Campaign Management API' |
|---|---|
| Description: | Provides functions to load and manage data from Apple Ads accounts using the 'Apple Ads Campaign Management API' <https://developer.apple.com/documentation/apple_ads>. |
| Authors: | Alexey Seleznev [aut, cre] (ORCID: <https://orcid.org/0000-0003-0410-7385>), Netpeak [cph] |
| Maintainer: | Alexey Seleznev <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 0.1.3 |
| Built: | 2026-05-25 09:14:09 UTC |
| Source: | https://github.com/selesnow/rappleads |
Apple Ads Authorization
apl_auth( client_id = Sys.getenv("APL_CLIENT_ID"), team_id = Sys.getenv("APL_TEAM_ID"), key_id = Sys.getenv("APL_KEY_ID"), private_key_path = Sys.getenv("APL_PRIVATE_KEY_PATH"), account_name = Sys.getenv("APL_ACCOUNT_NAME"), cache_path = rappdirs::site_data_dir("rappleads") )apl_auth( client_id = Sys.getenv("APL_CLIENT_ID"), team_id = Sys.getenv("APL_TEAM_ID"), key_id = Sys.getenv("APL_KEY_ID"), private_key_path = Sys.getenv("APL_PRIVATE_KEY_PATH"), account_name = Sys.getenv("APL_ACCOUNT_NAME"), cache_path = rappdirs::site_data_dir("rappleads") )
client_id |
You receive your clientId when you upload a public key. |
team_id |
The client secret is a JWT that you create and sign with your private key. |
key_id |
The value is your keyId that returns when you upload a public key. |
private_key_path |
Path to the |
account_name |
Your apple ads account name |
cache_path |
Path to the directory where cached authentication data will be stored. |
This implementation process guides you through the following steps:
Invite users with API permissions.
Generate a private-public key pair.
Extract a public key from your persisted private key.
Upload a public key.
Set system environments variables.
Request an access token.
API users need to create a private key. If you’re using MacOS or a UNIX-like operating system, OpenSSL works natively. If you’re on a Windows platform, you need to download OpenSSL.
openssl ecparam -genkey -name prime256v1 -noout -out private-key.pem
openssl ec -in private-key.pem -pubout -out public-key.pem
Open the public-key.pem file in a text editor and copy the public key, including the begin and end lines.
Follow these steps to upload your public key:
From the Ads UI, choose Account Settings > API. Paste the key created in the above section into the Public Key field.
Click Save. A group of credentials displays as a code block above the public key field. Use your clientId, teamId, and keyId to create a client secret.
Run usethis::edit_r_environ() and set variables:
APL_CLIENT_ID
APL_TEAM_ID
APL_KEY_ID
APL_PRIVATE_KEY_PATH
APL_ACCOUNT_NAME
Once the environment variables listed above are set, no further action is required from you — any function from the package will automatically request and refresh the access token when executed.
For more information see API Oauth documentation.
character with access_token
Get access_token
apl_get_access_token( client_id, jwt_data, account_name, cache_path = rappdirs::site_data_dir("rappleads") )apl_get_access_token( client_id, jwt_data, account_name, cache_path = rappdirs::site_data_dir("rappleads") )
client_id |
You receive your clientId when you upload a public key. |
jwt_data |
JWT object |
account_name |
Your apple ads account name |
cache_path |
Path to the directory where cached authentication data will be stored. |
access_token object
Get Ad Group-Level Reports
apl_get_ad_group_report( org_id = apl_get_me_details()$parentOrgId, campaign_id = apl_get_campaigns()$id, start_date = Sys.Date() - 8, end_date = Sys.Date() - 1, group_by = NULL, granularity = c("DAILY", "HOURLY", "WEEKLY", "MONTHLY") )apl_get_ad_group_report( org_id = apl_get_me_details()$parentOrgId, campaign_id = apl_get_campaigns()$id, start_date = Sys.Date() - 8, end_date = Sys.Date() - 1, group_by = NULL, granularity = c("DAILY", "HOURLY", "WEEKLY", "MONTHLY") )
org_id |
The value is your orgId. |
campaign_id |
The unique identifier for the campaign. |
start_date |
Start reporting date |
end_date |
End reporting date |
group_by |
Use the groupBy field to group responses by selected dimensions. If groupBy specifies age, gender, and geodimensions |
granularity |
The report data organized by hour, day, week, and month. |
tibble with ad group report
## Not run: adgr_rep <- apl_get_ad_group_report() ## End(Not run)## Not run: adgr_rep <- apl_get_ad_group_report() ## End(Not run)
Get Ad Groups
apl_get_ad_groups(org_id = apl_get_me_details()$parentOrgId)apl_get_ad_groups(org_id = apl_get_me_details()$parentOrgId)
org_id |
The value is your orgId. |
tibble with ad group metadata
## Not run: ad_group <- apl_get_ad_groups() ## End(Not run)## Not run: ad_group <- apl_get_ad_groups() ## End(Not run)
Get Ad-Level Reports
apl_get_ad_report( org_id = apl_get_me_details()$parentOrgId, campaign_id = apl_get_campaigns()$id, start_date = Sys.Date() - 8, end_date = Sys.Date() - 1, group_by = NULL, granularity = c("DAILY", "HOURLY", "WEEKLY", "MONTHLY") )apl_get_ad_report( org_id = apl_get_me_details()$parentOrgId, campaign_id = apl_get_campaigns()$id, start_date = Sys.Date() - 8, end_date = Sys.Date() - 1, group_by = NULL, granularity = c("DAILY", "HOURLY", "WEEKLY", "MONTHLY") )
org_id |
The value is your orgId. |
campaign_id |
The unique identifier for the campaign. |
start_date |
Start reporting date |
end_date |
End reporting date |
group_by |
Use the groupBy field to group responses by selected dimensions. If groupBy specifies age, gender, and geodimensions |
granularity |
The report data organized by hour, day, week, and month. |
tibble ad report
Get Ads
apl_get_ads(org_id = apl_get_me_details()$parentOrgId)apl_get_ads(org_id = apl_get_me_details()$parentOrgId)
org_id |
The value is your orgId. |
tibble with ads metadata
## Not run: ad <- apl_get_ads() ## End(Not run)## Not run: ad <- apl_get_ads() ## End(Not run)
Get List of Auth Cached Accounts
apl_get_auth_account_list()apl_get_auth_account_list()
character vector with accounts name
Get All Budget Orders
apl_get_budget_orders(org_id = apl_get_me_details()$parentOrgId)apl_get_budget_orders(org_id = apl_get_me_details()$parentOrgId)
org_id |
The value is your orgId. |
tibble with budget data
Get Campaign-Level Reports
apl_get_campaign_report( org_id = apl_get_me_details()$parentOrgId, start_date = Sys.Date() - 8, end_date = Sys.Date() - 1, group_by = NULL, granularity = c("DAILY", "HOURLY", "WEEKLY", "MONTHLY") )apl_get_campaign_report( org_id = apl_get_me_details()$parentOrgId, start_date = Sys.Date() - 8, end_date = Sys.Date() - 1, group_by = NULL, granularity = c("DAILY", "HOURLY", "WEEKLY", "MONTHLY") )
org_id |
The value is your orgId. |
start_date |
Start reporting date |
end_date |
End reporting date |
group_by |
Use the groupBy field to group responses by selected dimensions. If groupBy specifies age, gender, and geodimensions |
granularity |
The report data organized by hour, day, week, and month. |
tibble with report data
## Not run: camp_rep <- apl_get_campaign_report( org_id = 2623170, start_date = '2025-07-20', end_date = '2025-07-26', group_by = 'countryOrRegion' ) ## End(Not run)## Not run: camp_rep <- apl_get_campaign_report( org_id = 2623170, start_date = '2025-07-20', end_date = '2025-07-26', group_by = 'countryOrRegion' ) ## End(Not run)
Get All Campaigns
apl_get_campaigns(org_id = apl_get_me_details()$parentOrgId)apl_get_campaigns(org_id = apl_get_me_details()$parentOrgId)
org_id |
The value is your orgId. |
tibble with campaigns
## Not run: camp <- apl_get_campaigns(org_id = 2623170) ## End(Not run)## Not run: camp <- apl_get_campaigns(org_id = 2623170) ## End(Not run)
Get client secret
apl_get_client_secret( client_id, team_id, key_id, private_key_path, account_name, cache_path = rappdirs::site_data_dir("rappleads") )apl_get_client_secret( client_id, team_id, key_id, private_key_path, account_name, cache_path = rappdirs::site_data_dir("rappleads") )
client_id |
You receive your clientId when you upload a public key. |
team_id |
The client secret is a JWT that you create and sign with your private key. |
key_id |
The value is your keyId that returns when you upload a public key. |
private_key_path |
Path to the |
account_name |
Your apple ads account name |
cache_path |
Path to the directory where cached authentication data will be stored. |
jwt_data
Get All Creatives
apl_get_creatives(org_id = apl_get_me_details()$parentOrgId)apl_get_creatives(org_id = apl_get_me_details()$parentOrgId)
org_id |
The value is your orgId. |
tibble with campaigns
Get Keyword-Level Reports
apl_get_keyword_report( org_id = apl_get_me_details()$parentOrgId, campaign_id = apl_get_campaigns()$id, start_date = Sys.Date() - 8, end_date = Sys.Date() - 1, group_by = NULL, granularity = c("DAILY", "HOURLY", "WEEKLY", "MONTHLY") )apl_get_keyword_report( org_id = apl_get_me_details()$parentOrgId, campaign_id = apl_get_campaigns()$id, start_date = Sys.Date() - 8, end_date = Sys.Date() - 1, group_by = NULL, granularity = c("DAILY", "HOURLY", "WEEKLY", "MONTHLY") )
org_id |
The value is your orgId. |
campaign_id |
The unique identifier for the campaign. |
start_date |
Start reporting date |
end_date |
End reporting date |
group_by |
Use the groupBy field to group responses by selected dimensions. If groupBy specifies age, gender, and geodimensions |
granularity |
The report data organized by hour, day, week, and month. |
tibble with keyword report
## Not run: keyw_rep <- apl_get_keyword_report() ## End(Not run)## Not run: keyw_rep <- apl_get_keyword_report() ## End(Not run)
Get Me Details
apl_get_me_details()apl_get_me_details()
list with userId and parentOrgId
## Not run: me <- apl_get_me_details() ## End(Not run)## Not run: me <- apl_get_me_details() ## End(Not run)
Get Search Term-Level Reports
apl_get_search_term_report( org_id = apl_get_me_details()$parentOrgId, campaign_id = apl_get_campaigns()$id, start_date = Sys.Date() - 8, end_date = Sys.Date() - 1, group_by = NULL, granularity = c("DAILY", "HOURLY", "WEEKLY", "MONTHLY") )apl_get_search_term_report( org_id = apl_get_me_details()$parentOrgId, campaign_id = apl_get_campaigns()$id, start_date = Sys.Date() - 8, end_date = Sys.Date() - 1, group_by = NULL, granularity = c("DAILY", "HOURLY", "WEEKLY", "MONTHLY") )
org_id |
The value is your orgId. |
campaign_id |
The unique identifier for the campaign. |
start_date |
Start reporting date |
end_date |
End reporting date |
group_by |
Use the groupBy field to group responses by selected dimensions. If groupBy specifies age, gender, and geodimensions |
granularity |
The report data organized by hour, day, week, and month. |
tibble search term report
## Not run: ster_rep <- apl_get_search_term_report(start_date = '2025-06-01') ## End(Not run)## Not run: ster_rep <- apl_get_search_term_report(start_date = '2025-06-01') ## End(Not run)
Get User Access Control List
apl_get_user_acl()apl_get_user_acl()
tibble
## Not run: acs <- apl_get_user_acl() ## End(Not run)## Not run: acs <- apl_get_user_acl() ## End(Not run)
Make API request
apl_make_request(endpoint, parser, org_id = NULL, selector = NULL)apl_make_request(endpoint, parser, org_id = NULL, selector = NULL)
endpoint |
API endpoint |
parser |
Parser function |
org_id |
Organization ID |
selector |
Selector objects define what data the API returns when fetching resources. |
API parsed response
Set Apple Ads Account Name
apl_set_account_name(account_name)apl_set_account_name(account_name)
account_name |
Your apple ads account name |
nothing
Set Client ID
apl_set_client_id(client_id)apl_set_client_id(client_id)
client_id |
You receive your clientId when you upload a public key. |
nothing
Set KeyID
apl_set_key_id(key_id)apl_set_key_id(key_id)
key_id |
The value is your keyId that returns when you upload a public key. |
nothing
Set Privat Key Path
apl_set_private_key_path(private_key_path)apl_set_private_key_path(private_key_path)
private_key_path |
Path to the |
nothing
Set Team ID
apl_set_team_id(team_id)apl_set_team_id(team_id)
team_id |
The client secret is a JWT that you create and sign with your private key. |
nothing
Set Tinezone
apl_set_timezone(timezone)apl_set_timezone(timezone)
timezone |
You set the default timeZone during account creation through the Apple Search Ads UI. ORTZ (organization time zone) is the default. Possible Values: ORTZ, UTC |
nothing
Make request selector
make_selector( start_date = Sys.Date() - 8, end_date = Sys.Date() - 1, granularity = c("DAILY", "HOURLY", "WEEKLY", "MONTHLY"), sort_field = "startTime", time_zone = getOption("apl.time_zone"), group_by = NULL, part = NULL )make_selector( start_date = Sys.Date() - 8, end_date = Sys.Date() - 1, granularity = c("DAILY", "HOURLY", "WEEKLY", "MONTHLY"), sort_field = "startTime", time_zone = getOption("apl.time_zone"), group_by = NULL, part = NULL )
start_date |
start report date |
end_date |
end report date |
granularity |
The report data organized by hour, day, week, and month. |
sort_field |
Specify a field name and grouping to sort the records by ASCENDING or DESCENDING. |
time_zone |
You set the default timeZone during account creation through the Apple Search Ads UI. ORTZ |
group_by |
Use the groupBy field to group responses by selected dimensions. If groupBy specifies age, gender, and geodimensions |
part |
Part of selector |