Metadata-Version: 2.5
Name: asa-api-client
Version: 0.5.0
Summary: A modern Python client for the Apple Ads API with full type safety and async support
Project-URL: Homepage, https://github.com/SamPetherbridge/asa-api-client
Project-URL: Documentation, https://asa-api-client.peth.au
Project-URL: Repository, https://github.com/SamPetherbridge/asa-api-client
Project-URL: Issues, https://github.com/SamPetherbridge/asa-api-client/issues
Author-email: Sam Petherbridge <hello@peth.me>
License-Expression: MIT
License-File: LICENSE
Keywords: advertising,api,apple,apple-ads,asa,async,pydantic,search-ads
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: Pydantic :: 2
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Typing :: Typed
Requires-Python: >=3.13
Requires-Dist: httpx>=0.28.1
Requires-Dist: pydantic-settings>=2.6.0
Requires-Dist: pydantic>=2.10.0
Requires-Dist: pyjwt[crypto]>=2.15.1
Provides-Extra: cli
Requires-Dist: pandas>=2.2.0; extra == 'cli'
Requires-Dist: rich>=13.0.0; extra == 'cli'
Requires-Dist: typer>=0.15.0; extra == 'cli'
Requires-Dist: xlsxwriter>=3.2.0; extra == 'cli'
Provides-Extra: dev
Requires-Dist: mypy>=1.13.0; extra == 'dev'
Requires-Dist: openpyxl>=3.1.0; extra == 'dev'
Requires-Dist: pandas-stubs>=2.2.0; extra == 'dev'
Requires-Dist: pandas>=2.2.0; extra == 'dev'
Requires-Dist: pre-commit>=4.0.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
Requires-Dist: pytest-cov>=6.0.0; extra == 'dev'
Requires-Dist: pytest-httpx>=0.34.0; extra == 'dev'
Requires-Dist: pytest>=8.3.0; extra == 'dev'
Requires-Dist: rich>=13.0.0; extra == 'dev'
Requires-Dist: ruff>=0.8.0; extra == 'dev'
Requires-Dist: typer>=0.15.0; extra == 'dev'
Requires-Dist: types-openpyxl>=3.1.0; extra == 'dev'
Requires-Dist: xlsxwriter>=3.2.0; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.5.0; extra == 'docs'
Requires-Dist: mkdocs>=1.6.0; extra == 'docs'
Requires-Dist: mkdocstrings[python]>=0.27.0; extra == 'docs'
Provides-Extra: pandas
Requires-Dist: pandas>=2.2.0; extra == 'pandas'
Description-Content-Type: text/markdown

# ASA API Client

[![PyPI version](https://img.shields.io/pypi/v/asa-api-client.svg)](https://pypi.org/project/asa-api-client/)
[![Python](https://img.shields.io/pypi/pyversions/asa-api-client.svg)](https://pypi.org/project/asa-api-client/)
[![License](https://img.shields.io/github/license/SamPetherbridge/asa-api-client.svg)](https://github.com/SamPetherbridge/asa-api-client/blob/main/LICENSE)
[![CI](https://github.com/SamPetherbridge/asa-api-client/actions/workflows/ci.yml/badge.svg)](https://github.com/SamPetherbridge/asa-api-client/actions/workflows/ci.yml)

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](https://docs.astral.sh/uv/) (recommended):

```bash
uv add asa-api-client
```

Using pip:

```bash
pip install asa-api-client
```

Optional extras:

```bash
# 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

```python
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:

```bash
asa v1-smoke
```

## Environment Variables

```bash
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:

```bash
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

```python
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

```python
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

```python
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

```python
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

```python
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`:

```bash
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](https://asa-api-client.peth.au/guide/cli/).

## 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](https://asa-api-client.peth.au/guide/platform-api-v1/) when migrating existing v5 code.

## License

MIT License - Copyright (c) 2025 Peth Pty Ltd
