Platform API v1 & Migration
asa-api-client 1.0+ targets the Apple Ads Platform API v1 (https://api.ads.apple.com/v1) exclusively.
[!NOTE] Apple sunsets the legacy Campaign Management API v5 on January 26, 2027. Legacy
AppleSearchAdsClient(v5) was removed inasa-api-client1.0.0— pinasa-api-client<1.0if you still need v5 before the sunset.
Setup & Account Discovery
ASA_CLIENT_ID=SEARCHADS.xxxxxxxx-...
ASA_TEAM_ID=YOUR_TEAM_ID
ASA_KEY_ID=YOUR_KEY_ID
ASA_PRIVATE_KEY_PATH=/path/to/private-key.pem
ASA_AD_ACCOUNT_ID=123456
ad_account_id may be omitted at construction to auto-resolve via /v1/acls, or you can fan out across multiple accounts using client.with_account(...) (sharing the OAuth token cache and HTTP connection pools without mutating the parent client):
from asa_api_client import AppleAdsClient
with AppleAdsClient.from_env() as client:
# Auto-select sole account (or match prefer_org_id / ASA_ORG_ID)
client.resolve_ad_account()
# Or query multiple accounts independently
for acl in client.acls.list():
if acl.ad_account and acl.ad_account.id is not None:
scoped = client.with_account(acl.ad_account.id)
print(acl.ad_account.name, len(scoped.campaigns.query()))
Or run the bundled read-only smoke check:
Querying & Pagination
Resources expose POST <resource>/query endpoints backed by the fluent Query builder:
from asa_api_client import Query
page = client.campaigns.query(
Query()
.where("status", "EQUALS", "ENABLED")
.where("name", "CONTAINS_ANY", ["Brand", "Generic"], ignore_case=True)
.order_by("id", "DESC")
.page(size=100, fetch_total_count=True)
)
for campaign in page:
print(campaign.name)
# Automatic pagination across all pages
for campaign in client.campaigns.iter_all():
print(campaign.name)
Resource Coverage
- Core App Store ads:
campaigns,ad_groups,keywords,negative_keywords,ads,creatives,assets,product_pages,budget_orders,apps,geo,reports - Account & organization discovery:
me()/me_async(),acls,ad_accounts,orgs,advertiser_resources recommendations: Target-CPA and daily-budget recommendations withapply/dismissanditer_target_cpas/iter_daily_budgetssuggestions: Keyword, phrase, category, and target-CPA suggestions (iter_keywords,iter_phrases,iter_categories)insights: Impression share (iter_impression_share) and search-term popularity (iter_search_term_popularity)change_history: Account audit trail (query/iter_all/get_details)bulk: Bulk keyword and negative-keywordcreate_*,update_*, anddelete_*(lists over 5,000 items are automatically split into 5,000-item batches)- Apple Maps ads:
brands,locations,location_groups,business_categories,brand_rejection_reasons,brand_reports
Every sync method has an _async twin.
Error Handling, Bulk Operations & Retries
Responses carrying a top-level error block on HTTP 2xx raise PartialFailureError (exposing exc.details). In bulk operations with allow_partial_success=True (the default), Apple returns per-item success and error entries on each BulkItemResult:
from asa_api_client import PartialFailureError
try:
results = client.bulk.delete_keywords([101, 102], allow_partial_success=True)
for item in results:
if not item.success and item.error:
print(item.correlation_id, item.error.code, item.error.message)
except PartialFailureError as exc:
for detail in exc.details:
print(detail.get("code"), detail.get("message"))
Automatic retries with exponential backoff and bounded jitter cover rate limiting (429) and connection errors across all methods, and server errors (5xx) on idempotent requests (GET, PUT, DELETE, and read-only POST .../query endpoints). Non-idempotent POST writes never retry after 5xx or read timeouts so entities are not duplicated. Configure retry parameters on AppleAdsClient(..., max_retries=5, retry_initial_delay=5.0, retry_max_delay=120.0, retry_jitter=True).
Migration Crib (0.x / v5 → 1.0 / v1)
Legacy v5 (0.x) |
Platform API v1 (1.0+) |
|---|---|
AppleSearchAdsClient |
AppleAdsClient |
ASA_ORG_ID (orgId) |
ASA_AD_ACCOUNT_ID (adAccountId) or client.resolve_ad_account() |
client.campaigns.list() |
client.campaigns.query() / iter_all() |
Selector().where("status", "==", "ENABLED") |
Query().where("status", "EQUALS", "ENABLED") |
ACTIVE keyword status |
ENABLED |
adamId |
promotedObjectId + promotedObjectType |
defaultBidAmount |
bidStrategy.bid |
limit / offset |
pageSize / offset (+ fetchTotalCount) |
Nested client.campaigns(id).ad_groups |
Flat client.ad_groups + campaignId filter |
Lifetime budget, cpaCap |
Removed by Apple — use dailyBudget / bidStrategy |