AmazonAPIWrapper

A modern, high-performance, asynchronous and synchronous Python client for the Amazon Catalog APIs.

Supports both Amazon's modern Creators API (OAuth 2.0) and Product Advertising API 5.0 (PA-API 5.0) (AWS SigV4), with complete type hints, automatic OAuth token management, exponential backoff retries, and Python 3.9 through 3.13+ support.

Features

• ⚡ Async & Sync Support: Native support for standard synchronous code and asynchronous asyncio code powered by httpx.
• 🔐 Dual Protocol Engines:
  • Amazon Creators API: Modern OAuth 2.0 client credentials flow with automatic token caching and proactive refresh.
  • Amazon PA-API 5.0: AWS Signature Version 4 (SigV4) request signing for AWS IAM credentials.
• 📦 Complete Catalog Operations:
  • get_items: Detailed product lookup by ASIN (supports batching up to 10 items).
  • search_items: Rich product search with filters (actor, brand, category, price range, review rating, sort order).
  • get_variations: Retrieve child variation ASINs, colors, sizes, and price ranges.
  • get_browse_nodes: Browse category trees, parent ancestors, and child subcategories.
• 🌍 Global Marketplace Support: Native routing across 20+ Amazon global marketplaces (US, UK, DE, FR, JP, CA, IT, ES, IN, BR, MX, AU, AE, SG, SA, TR, NL, PL, SE, EG, BE).
• 🛡️ Robust Error Handling: Structured exception hierarchy (AmazonThrottlingError, AmazonAuthenticationError, AmazonBadRequestError, etc.) with built-in retry mechanisms for rate-limited requests.
• 🚀 Modern Tooling: Managed with uv, fully typed (PEP 561), and tested with pytest.

Installation

Install using pip:

pip install AmazonAPIWrapper

Or using uv:

uv add AmazonAPIWrapper

Quickstart

1. Amazon Creators API (Recommended)

To use the modern Amazon Creators API, you need your Credential ID and Credential Secret from Amazon Associates Central (Tools > Creators API).

Synchronous Example

from amazon import AmazonAPI, Marketplace

# Initialize client
with AmazonAPI(
    credential_id="YOUR_CREDENTIAL_ID",
    credential_secret="YOUR_CREDENTIAL_SECRET",
    marketplace=Marketplace.US,
) as api:
    # Look up products by ASIN
    response = api.get_items(item_ids=["B0041OSCBU"])

    if response.item:
        print(f"Title: {response.item.title}")
        print(f"Price: {response.item.price.display_amount}")
        print(f"Image: {response.item.image_url}")

    # Search products
    search_res = api.search_items(
        keywords="Python Programming",
        search_index="Books",
        item_count=5,
    )
    for item in search_res.items:
        print(f"{item.asin}: {item.title}")

Asynchronous Example (asyncio)

import asyncio
from amazon import AsyncAmazonAPI, Marketplace

async def main():
    async with AsyncAmazonAPI(
        credential_id="YOUR_CREDENTIAL_ID",
        credential_secret="YOUR_CREDENTIAL_SECRET",
        marketplace=Marketplace.US,
    ) as api:
        # Batch lookup
        response = await api.get_items(item_ids=["B0041OSCBU", "B0011ZK6PC"])
        for item in response.items:
            print(f"{item.asin} -> {item.title} ({item.price.display_amount if item.price else 'N/A'})")

asyncio.run(main())

2. PA-API 5.0 (AWS SigV4)

If you have legacy AWS IAM credentials for PA-API 5.0:

from amazon import AmazonPAAPI5, Marketplace

api = AmazonPAAPI5(
    access_key="YOUR_AWS_ACCESS_KEY",
    secret_key="YOUR_AWS_SECRET_KEY",
    associate_tag="yourtag-20",
    marketplace=Marketplace.US,
)

response = api.get_items(item_ids=["B0041OSCBU"])
print(response.item.title)

Detailed Operations

Product Lookup (get_items)

Retrieve rich metadata for up to 10 ASINs per call:

response = api.get_items(
    item_ids=["B0041OSCBU", "B08N5WRWNW"],
    resources=[
        "ItemInfo.Title",
        "ItemInfo.ByLineInfo",
        "Images.Primary.Large",
        "Offers.Listings.Price",
        "Offers.Listings.DeliveryInfo.IsPrimeEligible",
    ]
)

for item in response.items:
    print("ASIN:", item.asin)
    print("Title:", item.title)
    print("Brand:", item.item_info.brand if item.item_info else None)
    if item.offers and item.offers.listings:
        listing = item.offers.listings[0]
        print("Price:", listing.price.display_amount if listing.price else None)
        print("Prime Eligible:", listing.is_prime)

Product Search (search_items)

Search the Amazon catalog with advanced filters:

search_res = api.search_items(
    keywords="wireless headphones",
    brand="Sony",
    search_index="Electronics",
    min_price=5000,          # in cents (e.g. $50.00)
    max_price=30000,         # in cents (e.g. $300.00)
    min_reviews_rating=4,    # 4 stars and above
    sort_by="Price:LowToHigh",
    item_count=10,
    item_page=1,
)

print(f"Total Results: {search_res.pagination.total_result_count}")
for item in search_res.items:
    print(f"- {item.title}")

Product Variations (get_variations)

Get child variations (colors, sizes) for a parent ASIN:

variations = api.get_variations(
    asin="B0041OSCBU",
    variation_count=10,
)

if variations.variation_summary:
    print(f"Price Range: {variations.variation_summary.lowest_price.display_amount} - {variations.variation_summary.highest_price.display_amount}")

for item in variations.items:
    print(f"Child ASIN: {item.asin}, Color: {item.item_info.color}, Size: {item.item_info.size}")

Category Browse Nodes (get_browse_nodes)

Inspect category trees and subcategories:

nodes = api.get_browse_nodes(browse_node_ids=["17"])

node = nodes.browse_node
if node:
    print(f"Category: {node.display_name} (ID: {node.id})")
    if node.ancestor:
        print(f"Parent Category: {node.ancestor.display_name}")
    for child in node.children:
        print(f"Subcategory: {child.display_name} (ID: {child.id})")

Supported Marketplaces

You can specify marketplaces using the Marketplace enum, 2-letter country codes ('US', 'UK', 'DE', etc.), or domain names ('www.amazon.com'):

Error Handling

AmazonAPIWrapper provides a comprehensive typed exception hierarchy:

from amazon import AmazonAPI
from amazon.exceptions import (
    AmazonAPIError,
    AmazonAuthenticationError,
    AmazonBadRequestError,
    AmazonNotFoundError,
    AmazonThrottlingError,
    AmazonServerError,
)

try:
    with AmazonAPI(credential_id="...", credential_secret="...") as api:
        response = api.get_items(item_ids=["INVALID_ASIN"])
except AmazonThrottlingError as e:
    print(f"Rate limit exceeded (HTTP {e.status_code}): {e.message}")
except AmazonAuthenticationError as e:
    print(f"Invalid credentials (HTTP {e.status_code}): {e.message}")
except AmazonBadRequestError as e:
    print(f"Invalid request parameters: {e.message}")
except AmazonNotFoundError as e:
    print(f"Item not found: {e.message}")
except AmazonServerError as e:
    print(f"Amazon internal error: {e.message}")
except AmazonAPIError as e:
    print(f"General Amazon API error: {e.message}")

Migration from v0.0.x to v1.0.0

If you are updating from the legacy Python 2.7 XML wrapper (0.0.11):

1. Python 3.9+ Required: Update your Python runtime to Python 3.9 or higher.
2. Credentials: Switch from legacy XML keys to Creators API credentials (or pass access_key, secret_key, and associate_tag for PA-API 5.0).
3. Methods:
   • amz.item_lookup(ItemId=...) $\rightarrow$ api.get_items(item_ids=[...])
   • amz.item_search(Keywords=...) $\rightarrow$ api.search_items(keywords=...)
   • amz.node_browse_lookup(browse_node_id=...) $\rightarrow$ api.get_browse_nodes(browse_node_ids=[...])
4. Response Format: Instead of parsing BeautifulSoup XML objects, responses are now typed Python objects (response.item.title, response.items, response.to_dict()).

Development & Testing

This project uses uv for fast and reliable dependency management.

Setup

# Clone the repository
git clone https://github.com/lv10/amazonapi.git
cd amazonapi

# Install dependencies and sync environment
uv sync --all-extras

Running Tests

Run the full offline true unit test suite with coverage:

uv run pytest

Linting and Type Checking

# Lint code with Ruff
uv run ruff check .

# Type check with Mypy
uv run mypy amazon

Building Distribution

uv build

License

This project is licensed under the MIT License. See LICENSE for details.