Skip to content

v0.2.0 — Complete Apple Ads API v5 Coverage

Choose a tag to compare

View all tags
@SamPetherbridge SamPetherbridge released this 29 Mar 01:14
· 6 commits to main since this release
v0.2.0
67eeb86
This commit was signed with the committer’s verified signature.
SamPetherbridge Sam Petherbridge
SSH Key Fingerprint: AaZhrpOzL78EQnJAV09udKcO/SBFvyi9+Vad4ULHyyg
Verified
Learn about vigilant mode.

✨ Complete Apple Ads API v5 Coverage

This release brings full coverage of the Apple Search Ads Campaign Management API v5 with correct Pydantic models for every endpoint.

New Resources

  • Ads — Full CRUD for ad management (client.campaigns(id).ad_groups(id).ads)
  • Product Pages — List pages, get details, locale info (client.product_pages(adam_id))
  • Budget Orders — Read budget orders (client.budget_orders)
  • ACLs — List org/role access (client.acls)
  • App Search — Search eligible iOS apps (client.apps.search())
  • Geo Search — Search geographic locations for targeting (client.geo.search())
  • Countries/Regions — List supported countries with language details (client.countries_or_regions)

New Keyword Operations

  • keywords.delete_bulk() — Bulk delete targeting keywords
  • negative_keywords.update_bulk() — Bulk update negative keywords
  • negative_keywords.delete_bulk() — Bulk delete negative keywords

New Report Types

  • reports.ads() — Ad-level performance reports
  • reports.ad_group_keywords() — Ad group-scoped keyword reports
  • reports.ad_group_search_terms() — Ad group-scoped search term reports

v5 Model Corrections

  • Campaign: Fixed biddingStrategy (was bidStrategyType), targetCpa (was targetCostPerAcquisition), budgetOrders is now list[int], countryOrRegionServingStateReasons is now dict[str, list[str]]. Added creationTime, deleted, adChannelType, billingEvent to response model.
  • MetricData: All field aliases corrected to v5 names — tapInstalls, viewInstalls, totalInstalls, tapInstallCPI, avgCPM, totalAvgCPI, totalInstallRate, tapPreOrdersPlaced, etc.
  • AdGroup: Added deleted, automatedKeywordsRequired, biddingStrategy, paymentModel. Fixed serving state reason enum values.
  • Ad: Added creativeId. Fixed AdDisplayStatus values and AdServingStateReason enum (12 values).
  • ReportMetadata: Added ad-level fields (adId, adName, creativeType, creativeId, adDisplayStatus, language, productPageId).

Enum Completeness

  • CampaignServingStateReason: 38 values (was 28)
  • CampaignCountryOrRegionServingStateReason: 20 values (was 3)
  • AdGroupServingStateReason: 12 values with correct v5 names
  • AdServingStateReason: 12 values (was 5)
  • CreativeType: Added CREATIVE_SET
  • New: BudgetOrderStatus, BiddingStrategy enums

Deprecations

  • custom_reports.list_reports(), .get() — GET /custom-reports endpoint returns 403 since March 2026 (Apple replaced with Insights). Emits DeprecationWarning. POST-based create_impression_share() + wait_for_report() still works.

Breaking Changes

  • BidStrategyType renamed to BiddingStrategy (alias kept for backwards compat)
  • MetricData field names changed to match v5 API (e.g., installs → tap_installs)
  • Campaign.budget_orders type changed from list[dict] to list[int]
  • Campaign.country_or_region_serving_states replaced by country_or_region_serving_state_reasons
Assets 2
Loading