Skip to main content

amazon-ads-api-v1

PyPI version Python versions License: MIT

纯同步 Amazon Ads API 客户端。PyPI 安装名为 amazon-ads-api-v1,导入名为 ads_api。统一覆盖 v0 与 v1(SP、SB、SD、DSP、ST、SP Global、Accounts、Reporting、Ads Data Manager、Exports 等)。原生基于 httpx.Client,支持直接调用,无事件循环冲突。

Installation

pip install amazon-ads-api-v1
# 或
uv add amazon-ads-api-v1

Redis 缓存支持:

pip install "amazon-ads-api-v1[redis]"
# 或
uv add "amazon-ads-api-v1[redis]"

Quick Start

所有 API 方法仅接受 Pydantic model 实例,不支持 dict。默认 mode="dict",需要模型对象时传 mode="pydantic"。

使用 Access Token

from ads_api import AdsClient, AmazonAdsConfig, Region
from ads_api.models.v1.campaigns.sp import SPQueryCampaignRequest


def main() -> None:
    config = AmazonAdsConfig(
        access_token="your-access-token",
        client_id="your-client-id",
        region=Region.NA,
    )
    body = SPQueryCampaignRequest(
        adProductFilter={"include": ["SPONSORED_PRODUCTS"]},
        stateFilter={"include": ["ENABLED"]},
    )

    with AdsClient(config) as ads:
        resp = ads.v1.sp.campaigns.query_campaign(body)
        print(resp)


if __name__ == "__main__":
    main()

使用 Refresh Token(自动续期)

from ads_api import AdsClient, AmazonAdsConfig, Region
from ads_api.models.v1.campaigns.sp import SPQueryCampaignRequest


def main() -> None:
    config = AmazonAdsConfig(
        client_id="your-client-id",
        refresh_token="your-refresh-token",
        client_secret="your-client-secret",
        region=Region.NA,
    )
    body = SPQueryCampaignRequest(
        adProductFilter={"include": ["SPONSORED_PRODUCTS"]},
        stateFilter={"include": ["ENABLED"]},
    )

    with AdsClient(config) as ads:
        resp = ads.v1.sp.campaigns.query_campaign(body, mode="pydantic")
        print(resp.model_dump_json(indent=2))


if __name__ == "__main__":
    main()

Token Management

SDK 内置 OAuth token 生命周期管理。提供 refresh_token 与 client_secret 后会自动续期;缓存按字段推断:

from ads_api import AmazonAdsConfig, Region

# 自动续期,不使用磁盘 / Redis 缓存
config = AmazonAdsConfig(
    client_id="your-client-id",
    client_secret="your-client-secret",
    refresh_token="your-refresh-token",
    region=Region.NA,
)

# 文件缓存
config = AmazonAdsConfig(
    client_id="your-client-id",
    client_secret="your-client-secret",
    refresh_token="your-refresh-token",
    region=Region.NA,
    token_cache_dir="~/.cache/ads_api",
)

# Redis 缓存
config = AmazonAdsConfig(
    client_id="your-client-id",
    client_secret="your-client-secret",
    refresh_token="your-refresh-token",
    region=Region.NA,
    redis_url="redis://localhost:6379",
)

API 入口

with AdsClient(config) as ads:
    # v1
    ads.v1.sp.campaigns.query_campaign(body)
    ads.v1.sb.campaigns.query_campaign(body)
    ads.v1.sd.campaigns.query_campaign(body)
    ads.v1.selling_accounts.query_selling_account(body)
    ads.v1.reports.create_report(body)

    # v0
    ads.v0.accounts.profiles.list_profiles()
    ads.v0.portfolios.list_portfolios()
    ads.v0.sp_v3.campaigns.create_sponsored_products_campaigns(body)
    ads.v0.sb_v4.budget_rules.create_budget_rules_for_sb_campaigns(body)
    ads.v0.sd.creatives.create_creatives(body)

Login with Amazon (LWA) OAuth 支持

内置轻量高效的原生同步 OAuthClient,支持生成授权跳转 URL、授权码换取 Token、刷新 Token 与获取 LWA 用户档案:

from ads_api import AdsClient, OAuthClient, Region

oauth = OAuthClient(
    client_id="your-client-id",
    client_secret="your-client-secret",
    scope="advertising::campaign_management",
    redirect_uri="https://app.com/callback",
    region=Region.NA,
)

# 1. 生成带 state 防重放的授权 URL
auth_url, state = oauth.get_authorization_url()

# 2. 换取 Token 并拉起 AdsClient
with oauth:
    tokens = oauth.exchange_code_for_tokens(code)
    config = oauth.create_config(tokens, profile_id="123456789")
    with AdsClient(config) as ads:
        resp = ads.v1.sp.campaigns.query_campaign(body)

License

MIT

Metadata

Release files for amazon-ads-api-v1 0.12.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 amazon-ads-api-v1 0.12.0
File Size Uploaded Provenance Actions
amazon_ads_api_v1-0.12.0.tar.gz 414.0 kB With provenance Details for amazon_ads_api_v1-0.12.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for amazon-ads-api-v1 0.12.0
File Interpreter ABI Platform Actions
amazon_ads_api_v1-0.12.0-py3-none-any.whl Python 3 none any Details for amazon_ads_api_v1-0.12.0-py3-none-any.whl

Total release size: 1.1 MB

Release files / amazon_ads_api_v1-0.12.0.tar.gz

Download URL amazon_ads_api_v1-0.12.0.tar.gz
Size 414.0 kB
Tags Source
SHA-256 checksum
How to use checksums
71007045ffa2dfd6380c5f27a92b3d8de10ae3cf8546a4b094cad35460358d15
BLAKE2b-256 checksum
How to use checksums
39b856522dd553370b94752dc2c5a3dc403a0244a597fe30624ea57b44e2a5a3
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 5, 2026.

Transparency log

Release files / amazon_ads_api_v1-0.12.0-py3-none-any.whl

Download URL amazon_ads_api_v1-0.12.0-py3-none-any.whl
Size 663.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
61f85b492c8ffec2c174073f15f556b67dd6852f4d1faa984322dd85fea60599
BLAKE2b-256 checksum
How to use checksums
b44b1f90d107044b89a592e17df42fcaea5aac4d35954e1235cb19c8c38aec3e
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 5, 2026.

Transparency log

Security for amazon-ads-api-v1 0.12.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 amazon_ads_api_v1-0.12.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 5, 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.

Release history Release notifications | RSS feed

This release

0.12.0 This release

2 release files Full provenance

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