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.
budget_orders	BudgetOrderResource	Resource for reading budget orders.
acls	ACLResource	Resource for reading access control lists.
apps	AppResource	Resource for searching eligible apps.
geo	GeoResource	Resource for searching geographic locations.

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)