Skip to main content

ASA API Client

PyPI version Python License CI

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.typed included)
  • 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 _async counterpart on the same client, with multi-account scoping via client.with_account(...)
  • Automatic Pagination — iter_* and *_async helpers plus fluent Query builder across entity, report, insight, recommendation, suggestion, and audit endpoints
  • Reports with Pandas — report.to_records() and optional report.to_dataframe() export across all App Store and Apple Maps report levels
  • Analysis CLI — Generate multi-sheet Excel performance & search-popularity workbooks via asa-client 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-client analyze / asa-client 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-client 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-client analyze (named asa-client so it never collides with the full asa command from asa-api-cli):

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

asa-client 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.1

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 1.0.1
File Size Uploaded Provenance Actions
asa_api_client-1.0.1.tar.gz 350.0 kB With provenance Details for asa_api_client-1.0.1.tar.gz

Built distribution (wheel)

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

Total release size: 506.5 kB

Release files / asa_api_client-1.0.1.tar.gz

Download URL asa_api_client-1.0.1.tar.gz
Size 350.0 kB
Tags Source
SHA-256 checksum
How to use checksums
0d3af7b80f0858d4acb9ce50618013dada69070125e27c670d67aaf74e8c41cc
BLAKE2b-256 checksum
How to use checksums
6e5e341136bc96b99ecf08d72531321f26b00361ed696a9ae63af6d45ed37c22
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 16, 2026.

Transparency log

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

Download URL asa_api_client-1.0.1-py3-none-any.whl
Size 156.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
addf6b7aadd5104c0ef3ad7ca2e92762d9b75bec047d9df90fee2a2066d711bc
BLAKE2b-256 checksum
How to use checksums
df7ed60fab6186fce739cbb24969df3cea1a1087fb4cc434338206419e4fcd14
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 16, 2026.

Transparency log

Security for asa-api-client 1.0.1

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-1.0.1.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 16, 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