Patch release. No public API changes — rolls up post-0.2.0 maintenance and CI fixes.

Fixes

• 🐛 Allow list[int] JSON body for bulk-delete endpoints (mypy type correctness; runtime behavior unchanged)
• 🎨 Apply ruff formatting across source files
• 🔧 Sync uv.lock with the package version (#16)

Tooling / CI

• 👷 Add uv lock --check CI guard to prevent lockfile drift (#16)
• 👷 Bump GitHub Actions: checkout 4→6, setup-uv 4→7, configure-pages 4→5, upload-pages-artifact 3→4 (#4–#7)

Full Changelog: v0.2.0...v0.2.1

✨ 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

What's New

Report Reuse to Avoid Daily Limit

Apple limits impression share reports to 10 per day. This release automatically reuses existing completed reports when possible:

• get_impression_share() now checks for existing reports before creating new ones
• Uses 1-day tolerance on end date to handle day rollover scenarios
• Prefers exact matches, falls back to close matches

Debug Logging

Set ASA_DEBUG=1 environment variable to see all API requests:

$ ASA_DEBUG=1 uv run asa impression-share analyze
[custom-reports] GET custom-reports
[custom-reports] Reusing existing report 57861436
✓ Retrieved 65 records

Bug Fixes

• Fixed list_reports() - removed unsupported pagination params that caused HTTP 400

Full Changelog

v0.1.5...v0.1.6

• Increase default retries from 3 to 5
• Increase initial delay from 1s to 5s (better for Apple rate limits)
• Increase max delay from 60s to 120s
• Add visible retry progress output to stderr

Add retry with exponential backoff to CustomReportResource for impression share report creation

What's Changed

Features

• Automatic retry with exponential backoff for rate limiting (429) and server errors (5xx)
  • Exponential backoff: 1s, 2s, 4s... up to 60s max
  • Respects Retry-After header when present
  • 3 retries by default (configurable via max_retries param)
  • Applies to both sync and async request methods
  • Logs retry attempts with delay information

This helps handle Apple's API rate limits gracefully, automatically retrying requests when the API returns 429 errors.

What's New

• Impression Share Reports: Added full support for Apple Search Ads Custom Reports API

  • ImpressionShareReport, ImpressionShareReportRow, ImpressionShareReportRequest models
  • CustomReportResource with create_impression_share(), get(), wait_for_report() methods
  • Automatic CSV download and parsing when report completes
  • Both sync and async support

• Pre-commit Hooks: Added ruff and mypy pre-commit hooks for code quality

Changes

• Fixed author name to "Sam Petherbridge"
• Fixed author email to "hello@peth.me"

No functional changes from v0.1.0.

ASA API Client v0.1.0

A modern, fully-typed Python client for the Apple Search Ads API with async support and Pydantic models.

Features

• Full Type Safety - Complete type hints with strict mypy compliance
• Async Support - Both sync and async methods in a unified client
• Pydantic Models - Validated request/response models
• Resource-based API - Intuitive client.campaigns.list() pattern
• Automatic Pagination - iter_all() and iter_all_async() helpers
• Reports with Pandas - Optional DataFrame export

Installation

pip install asa-api-client

Or with uv:

uv add asa-api-client

Quick Start

from asa_api_client import AppleSearchAdsClient
client = AppleSearchAdsClient.from_env()
with client:
 campaigns = client.campaigns.list()
 for campaign in campaigns:
 print(f"{campaign.name}: {campaign.status}")

Resources

• Campaigns - List, get, create, update campaigns
• Ad Groups - Manage ad groups within campaigns
• Keywords - Bulk create and manage keywords
• Reports - Generate performance reports with optional DataFrame export

Documentation

Full documentation available at asa-api-client.peth.au

Requirements

• Python 3.13+
• Valid Apple Search Ads API credentials

License

MIT License - Copyright (c) 2025 Peth Pty Ltd