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. Also ships the legacy Campaign Management API v5 client (AppleSearchAdsClient) ahead of Apple's January 26, 2027 v5 sunset.

Features

  • Full Type Safety — Complete type hints with strict mypy + Pydantic v2 compliance
  • Platform API v1 First — Campaigns, ad groups, keywords, ads, creatives, recommendations, insights, search-term popularity, change history, bulk operations, and Apple Maps brand ads
  • Sync & Async — Every method has an _async counterpart on the same client
  • Automatic Pagination — iter_all() and iter_all_async() helpers plus fluent Query builder
  • Reports with Pandas — Optional report.to_dataframe() export across all v1 and v5 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 v1-smoke)
uv add "asa-api-client[cli]"

Quick Start

from asa_api_client import AppleAdsClient
from asa_api_client.v1 import 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? Discover accessible accounts with the bundled read-only smoke check:

asa v1-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.v1 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
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 uses the Platform API v1 by default (and auto-selects your ad account from /v1/acls when ASA_AD_ACCOUNT_ID is omitted). For full details, see the CLI guide.

Legacy Campaign Management API v5

AppleSearchAdsClient remains available for legacy v5 workflows until Apple shuts down v5 on January 26, 2027 (AppleSearchAdsClient emits a DeprecationWarning on construction). See the Platform API v1 migration guide when migrating existing v5 code.

License

MIT License - Copyright (c) 2025 Peth Pty Ltd

Metadata

Release files for asa-api-client 0.5.0

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

Built distribution (wheel)

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

Total release size: 590.1 kB

Release files / asa_api_client-0.5.0.tar.gz

Download URL asa_api_client-0.5.0.tar.gz
Size 382.3 kB
Tags Source
SHA-256 checksum
How to use checksums
39eeeefa0fffa9c846f771c085839e91fd414b216ee5ac8ec3273bd6ccdf0946
BLAKE2b-256 checksum
How to use checksums
5142de2101ace14ff11d51083dfe9303100d1a2fe57032b18d247231f6659a1c
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 14, 2026.

Transparency log

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

Download URL asa_api_client-0.5.0-py3-none-any.whl
Size 207.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
eb51f468b23fbeed5c7e75497bc851d159b5a2a04212b2a686cd8a69b30c9c0c
BLAKE2b-256 checksum
How to use checksums
d6dfdb188da0c39604bb8ac9ce1561a1f821c133e8532f293e51102c3ea5cf61
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 14, 2026.

Transparency log

Security for asa-api-client 0.5.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.

Select from 2 files

Attestation for asa_api_client-0.5.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 14, 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