Client Reference

asa_api_client.AppleSearchAdsClient

Client for interacting with the Apple Search Ads API.

This is the main entry point for the library. It provides access to all API resources through a structured, resource-based interface.

The client supports both synchronous and asynchronous operations. Async methods are available with the _async suffix.

Attributes:

Name	Type	Description
org_id		The Apple Search Ads organization ID.
campaigns	CampaignResource	Resource for managing campaigns.
reports	ReportResource	Resource for generating reports.
custom_reports	CustomReportResource	Resource for impression share reports.

Example

Basic usage::

from asa_api_client import AppleSearchAdsClient

client = AppleSearchAdsClient(
    client_id="SEARCHADS.abc123",
    team_id="TEAM123",
    key_id="KEY123",
    org_id=123456,
    private_key_path="path/to/private-key.pem",
)

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

# Create a campaign
from asa_api_client.models import CampaignCreate, Money, CampaignSupplySource

new_campaign = client.campaigns.create(
    CampaignCreate(
        name="My Campaign",
        budget_amount=Money.usd(10000),
        adam_id=123456789,
        countries_or_regions=["US"],
        supply_sources=[CampaignSupplySource.APPSTORE_SEARCH_RESULTS],
    )
)

Async usage::

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

Context manager::

with AppleSearchAdsClient(...) as client:
    campaigns = client.campaigns.list()

From environment variables::

# Set these environment variables:
# ASA_CLIENT_ID, ASA_TEAM_ID, ASA_KEY_ID, ASA_ORG_ID
# ASA_PRIVATE_KEY or ASA_PRIVATE_KEY_PATH

client = AppleSearchAdsClient.from_env()

campaigns property

Get the campaigns resource.

Returns:

Type	Description
CampaignResource	CampaignResource for managing campaigns.

Example

List all campaigns::

campaigns = client.campaigns.list()

Access ad groups in a campaign::

ad_groups = client.campaigns(123).ad_groups.list()

reports property

Get the reports resource.

Returns:

Type	Description
ReportResource	ReportResource for generating reports.

Example

Get campaign report::

from datetime import date

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

from_env(*, env_file='.env', base_url=DEFAULT_BASE_URL, timeout=30.0) classmethod

Create a client from environment variables and .env file.

Loads configuration from environment variables and optionally from a .env file. Environment variables take precedence.

Required settings (via env vars or .env file): - ASA_CLIENT_ID - ASA_TEAM_ID - ASA_KEY_ID - ASA_ORG_ID - ASA_PRIVATE_KEY or ASA_PRIVATE_KEY_PATH

Parameters:

Name	Type	Description	Default
env_file	str | Path | None	Path to .env file to load. Set to None to skip loading from file. Defaults to ".env".	'.env'
base_url	str	The API base URL.	DEFAULT_BASE_URL
timeout	float	Request timeout in seconds.	30.0

Returns:

Type	Description
Self	A configured AppleSearchAdsClient instance.

Raises:

Type	Description
ConfigurationError	If required settings are missing or invalid.

Example

Load from .env file::

client = AppleSearchAdsClient.from_env()

Load from a specific env file::

client = AppleSearchAdsClient.from_env(env_file=".env.production")

Only use environment variables::

client = AppleSearchAdsClient.from_env(env_file=None)