Skip to main content

ASA API Client

PyPI version Python License CI

A modern, fully-typed Python client for the Apple Ads APIs with async support and Pydantic models — covering both the new Apple Ads Platform API v1 and the legacy Campaign Management API v5 (sunset January 26, 2027).

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

Using uv (recommended):

uv add asa-api-client

Using pip:

pip install asa-api-client

With pandas support:

uv add "asa-api-client[pandas]"
# or
pip install "asa-api-client[pandas]"

Quick Start

from asa_api_client import AppleSearchAdsClient

# From environment variables
client = AppleSearchAdsClient.from_env()

# Or explicit configuration
client = AppleSearchAdsClient(
    client_id="SEARCHADS.xxx",
    team_id="SEARCHADS.xxx",
    key_id="xxx",
    org_id=123456,
    private_key_path="private-key.pem",
)

# List campaigns
with client:
    campaigns = client.campaigns.list()
    for campaign in campaigns:
        print(f"{campaign.name}: {campaign.status}")

Platform API v1

Apple's new Platform API v1 replaces v5 (which stops working on 2027-01-26). The v1 client ships alongside the v5 client with the same credentials — just add your ad account ID:

from asa_api_client import AppleAdsClient
from asa_api_client.v1 import Query

client = AppleAdsClient.from_env()  # reads ASA_* plus ASA_AD_ACCOUNT_ID

with client:
    # Flat query-based API with typed filters
    enabled = client.campaigns.query(Query().where("status", "EQUALS", "ENABLED"))

    # v1-only features
    recs = client.recommendations
    popularity = client.insights
    history = client.change_history
    bulk = client.bulk

Don't know your ad account ID? Run the read-only smoke check — it discovers accounts and validates the whole integration against the live API:

asa v1-smoke

See the Platform API v1 guide for the full migration crib and resource reference. Import v1 symbols from the package root (AppleAdsClient) — internal layout may change when v5 is removed.

Environment Variables

export ASA_CLIENT_ID="SEARCHADS.your-client-id"
export ASA_TEAM_ID="SEARCHADS.your-team-id"
export ASA_KEY_ID="your-key-id"
export ASA_ORG_ID="123456"
export ASA_PRIVATE_KEY_PATH="/path/to/private-key.pem"
export ASA_AD_ACCOUNT_ID="123456"  # Platform API v1 only

Or use a .env file:

ASA_CLIENT_ID=SEARCHADS.your-client-id
ASA_TEAM_ID=SEARCHADS.your-team-id
ASA_KEY_ID=your-key-id
ASA_ORG_ID=123456
ASA_PRIVATE_KEY_PATH=private-key.pem
ASA_AD_ACCOUNT_ID=123456  # Platform API v1 only

Resources

Campaigns

# List all campaigns
campaigns = client.campaigns.list()

# Get a specific campaign
campaign = client.campaigns.get(campaign_id)

# Find with filters
from asa_api_client.models import Selector
enabled = client.campaigns.find(
    Selector().where("status", "==", "ENABLED")
)

# Create a campaign
from asa_api_client.models import CampaignCreate, Money, CampaignSupplySource
campaign = client.campaigns.create(
    CampaignCreate(
        name="My Campaign",
        adam_id=123456789,
        countries_or_regions=["US"],
        daily_budget_amount=Money(amount="100", currency="USD"),
        supply_sources=[CampaignSupplySource.APPSTORE_SEARCH_RESULTS],
    )
)

Ad Groups

# Access ad groups through campaign
ad_groups = client.campaigns(campaign_id).ad_groups.list()

# Create an ad group
from asa_api_client.models import AdGroupCreate
ad_group = client.campaigns(campaign_id).ad_groups.create(
    AdGroupCreate(
        name="My Ad Group",
        default_bid_amount=Money(amount="1.00", currency="USD"),
    )
)

Keywords

# List keywords in an ad group
keywords = client.campaigns(campaign_id).ad_groups(ad_group_id).keywords.list()

# Create keywords (bulk only)
from asa_api_client.models import KeywordCreate, KeywordMatchType
result = client.campaigns(campaign_id).ad_groups(ad_group_id).keywords.create_bulk([
    KeywordCreate(
        text="my keyword",
        match_type=KeywordMatchType.EXACT,
        bid_amount=Money(amount="1.50", currency="USD"),
    )
])

Reports

from datetime import date

# Campaign report
report = client.reports.campaigns(
    start_date=date(2024, 1, 1),
    end_date=date(2024, 1, 31),
)

# Convert to DataFrame (requires pandas)
df = report.to_dataframe()

Async Usage

import asyncio

async def main():
    client = AppleSearchAdsClient.from_env()

    async with client:
        campaigns = await client.campaigns.list_async()

        # Async iteration
        async for campaign in client.campaigns.iter_all_async():
            print(campaign.name)

asyncio.run(main())

CLI

Generate a formatted Excel analysis workbook with the included asa analyze CLI:

pip install "asa-api-client[cli]"
asa analyze --period 90d --output report.xlsx

The workbook includes a summary sheet with KPIs and trends, formatted analysis sheets per reporting level, and raw daily data for pivoting. For details, see the CLI guide.

License

MIT License - Copyright (c) 2025 Peth Pty Ltd

Metadata

Release files for asa-api-client 0.4.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for asa-api-client 0.4.2
File Size Uploaded Provenance Actions
asa_api_client-0.4.2.tar.gz 373.5 kB With provenance Details for asa_api_client-0.4.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for asa-api-client 0.4.2
File Interpreter ABI Platform Actions
asa_api_client-0.4.2-py3-none-any.whl Python 3 none any Details for asa_api_client-0.4.2-py3-none-any.whl

Total release size: 577.5 kB

Release files / asa_api_client-0.4.2.tar.gz

Download URL asa_api_client-0.4.2.tar.gz
Size 373.5 kB
Tags Source
SHA-256 checksum
How to use checksums
9cffc6794d724c8b072ce6dada43f2542264233245ff500803e7ca5f984baba3
BLAKE2b-256 checksum
How to use checksums
d30aa4d20ea1348ce6a2a449c00b93c09197da5842c72b540752995ae9605929
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 5, 2026.

Transparency log

Release files / asa_api_client-0.4.2-py3-none-any.whl

Download URL asa_api_client-0.4.2-py3-none-any.whl
Size 204.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
c5dc4d4750cb10a9fc55129f220354d4d7a0ea3c8350161b8611548a5777370f
BLAKE2b-256 checksum
How to use checksums
b3949e4648307618d9699e03727b2b0c7f1a92bdadc93bb96111759c68129da8
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 5, 2026.

Transparency log

Security for asa-api-client 0.4.2

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.

Select from 2 files

Attestation for asa_api_client-0.4.2.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 5, 2026.

Transparency log

A 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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page