ASA API Client
A modern, fully-typed Python client for the Apple Ads Platform API v1 (App Store and Apple Maps ads) with async support and Pydantic models.
Features
- Full Type Safety — Complete type hints with strict
mypy+ Pydantic v2 compliance (py.typedincluded) - Complete Platform API v1 Coverage — Campaigns, ad groups, keywords, ads, creatives, recommendations, insights, search-term popularity, suggestions, change history, bulk operations, and Apple Maps brand ads
- Sync & Async — Every method has an
_asynccounterpart on the same client, with multi-account scoping viaclient.with_account(...) - Automatic Pagination —
iter_*and*_asynchelpers plus fluentQuerybuilder across entity, report, insight, recommendation, suggestion, and audit endpoints - Reports with Pandas —
report.to_records()and optionalreport.to_dataframe()export across all App Store and Apple Maps report levels - Analysis CLI — Generate multi-sheet Excel performance & search-popularity workbooks via
asa analyze
Installation
Using uv (recommended):
uv add asa-api-client
Using pip:
pip install asa-api-client
Optional extras:
# DataFrame export (report.to_dataframe())
uv add "asa-api-client[pandas]"
# Excel analysis CLI (asa analyze / asa smoke)
uv add "asa-api-client[cli]"
Quick Start
from asa_api_client import AppleAdsClient, Query
# Reads ASA_* variables from the environment or .env
client = AppleAdsClient.from_env()
# Or pass credentials explicitly
client = AppleAdsClient(
client_id="SEARCHADS.xxx",
team_id="TEAM123",
key_id="KEY123",
ad_account_id="123456",
private_key_path="private-key.pem",
)
with client:
enabled = client.campaigns.query(Query().where("status", "EQUALS", "ENABLED"))
for campaign in enabled:
print(f"{campaign.id}: {campaign.name} ({campaign.display_status})")
Don't know your ad_account_id yet? Auto-resolve it via client.resolve_ad_account(), or run the bundled read-only smoke check:
asa smoke
Environment Variables
export ASA_CLIENT_ID="SEARCHADS.your-client-id"
export ASA_TEAM_ID="your-team-id"
export ASA_KEY_ID="your-key-id"
export ASA_AD_ACCOUNT_ID="123456"
export ASA_PRIVATE_KEY_PATH="/path/to/private-key.pem"
Or use a .env file:
ASA_CLIENT_ID=SEARCHADS.your-client-id
ASA_TEAM_ID=your-team-id
ASA_KEY_ID=your-key-id
ASA_AD_ACCOUNT_ID=123456
ASA_PRIVATE_KEY_PATH=private-key.pem
Resources
Campaigns
from asa_api_client import Query
from asa_api_client.v1.models.base import Money
from asa_api_client.v1.models.campaigns import (
BillingEvent,
CampaignCreate,
CampaignTargeting,
CampaignUpdate,
DailyBudget,
PromotedObjectType,
)
from asa_api_client.v1.models.shared import TargetingData
# Query or iterate all campaigns
page = client.campaigns.query(Query().where("status", "EQUALS", "ENABLED"))
all_campaigns = list(client.campaigns.iter_all())
# Get a specific campaign
campaign = client.campaigns.get(campaign_id)
# Create an App Store campaign
created = client.campaigns.create(
CampaignCreate(
ad_account_id=123456,
name="US Search",
billing_event=BillingEvent.TAPS,
promoted_object_type=PromotedObjectType.APPSTORE_APP,
promoted_object_id="987654321",
daily_budget=DailyBudget(value=Money(amount="100.00", currency="USD")),
targeting=CampaignTargeting(
supply_source=TargetingData(include=["APPSTORE"]),
supply_placement=TargetingData(include=["APPSTORE_SEARCH_RESULTS"]),
country_or_region=TargetingData(include=["US"]),
),
)
)
# Update daily budget
client.campaigns.update(
campaign_id,
CampaignUpdate(daily_budget=DailyBudget(value=Money(amount="150.00", currency="USD"))),
)
Ad Groups
from asa_api_client.v1.models.ad_groups import AdGroupCreate, PricingModel
from asa_api_client.v1.models.shared import BidStrategy, BidStrategyGoal, BidStrategyType
ad_groups = client.ad_groups.query(Query().where("campaignId", "EQUALS", str(campaign_id)))
ad_group = client.ad_groups.create(
AdGroupCreate(
name="Exact Core",
campaign_id=campaign_id,
pricing_model=PricingModel.CPT,
bid_strategy=BidStrategy(
bid_strategy_type=BidStrategyType.MANUAL_CPT,
bid_strategy_goal=BidStrategyGoal.TAP,
bid=Money(amount="1.50", currency="USD"),
),
)
)
Keywords & Bulk Operations
from asa_api_client.v1.models.bulk import BulkKeywordUpdate
from asa_api_client.v1.models.keywords import KeywordCreate, KeywordMatchType
# Query keywords in an ad group
keywords = client.keywords.query(Query().where("adGroupId", "EQUALS", str(ad_group_id)))
# Bulk create, update, and delete keywords (automatically batched at 5,000 items)
created = client.bulk.create_keywords(
[
KeywordCreate(
ad_group_id=ad_group_id,
text="budget tracker",
match_type=KeywordMatchType.EXACT,
bid=Money(amount="1.75", currency="USD"),
)
]
)
client.bulk.update_keywords(
[BulkKeywordUpdate(id=keyword_id, bid=Money(amount="2.00", currency="USD"))]
)
client.bulk.delete_keywords([keyword_id])
Reports
from datetime import date
from asa_api_client.v1.models.reports import (
AppsReportingRequest,
ReportGranularity,
ReportTimeRange,
)
report = client.reports.campaigns(
AppsReportingRequest(
time_range=ReportTimeRange(
start=date(2026, 8, 1),
end=date(2026, 8, 31),
granularity=ReportGranularity.DAILY,
)
)
)
# Convert to a pandas DataFrame (requires asa-api-client[pandas])
df = report.to_dataframe()
Async Usage
import asyncio
from asa_api_client import AppleAdsClient
async def main() -> None:
async with AppleAdsClient.from_env() as client:
async for campaign in client.campaigns.iter_all_async():
print(campaign.name)
asyncio.run(main())
CLI
Generate a formatted Excel performance and search-popularity workbook with asa analyze:
pip install "asa-api-client[cli]"
asa analyze --period 90d --output report.xlsx
asa analyze auto-selects your ad account from /v1/acls when ASA_AD_ACCOUNT_ID is omitted. See the CLI guide for all options.
Legacy Campaign Management API v5
Support for Apple's deprecated Campaign Management API v5 (AppleSearchAdsClient, sunset January 26, 2027) was removed in 1.0.0. Pin asa-api-client<1.0 if you need v5, or see the v5 → v1 migration guide.
License
MIT License - Copyright (c) 2025 Peth Pty Ltd
Metadata
Release files for asa-api-client 1.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| asa_api_client-1.0.0.tar.gz | 347.2 kB | With provenance | Details for asa_api_client-1.0.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| asa_api_client-1.0.0-py3-none-any.whl | Python 3 | none | any | Details for asa_api_client-1.0.0-py3-none-any.whl |
Total release size: 503.5 kB
Release files / asa_api_client-1.0.0.tar.gz
| Download URL | asa_api_client-1.0.0.tar.gz |
|---|---|
| Size | 347.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
b9d582a56f189ffd3e0d5f6f623fcfe83636ee8956806cdfd0619ad33e3e0d7c
|
|
BLAKE2b-256 checksum How to use checksums |
17e4ba104c14a863aa8722ffd6d34b125bebf5e995463ad91eec61c9de1b77c8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.
Transparency logRelease files / asa_api_client-1.0.0-py3-none-any.whl
| Download URL | asa_api_client-1.0.0-py3-none-any.whl |
|---|---|
| Size | 156.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
b38122a45b26e5d3f4ca9df25ffe967cc2cd117ed677f8afb876fe89a4dd82b8
|
|
BLAKE2b-256 checksum How to use checksums |
e34366a2d652af2a8632c8e5366b3538c14b8fd2854f5f49760bf75be5940717
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.
Transparency logSecurity for asa-api-client 1.0.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for asa_api_client-1.0.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.