### Basic usage examples

Source: https://github.com/sergioteula/python-amazon-paapi/blob/master/docs/pages/migration-guide-6.md

Examples of how to use the main methods after migration.

```python
# Get items
items = amazon.get_items(['B01N5IB20Q'])

# Search items
results = amazon.search_items(keywords='nintendo')

# Get variations
variations = amazon.get_variations('B01N5IB20Q')

# Get browse nodes
nodes = amazon.get_browse_nodes(['667049031'])
```

--------------------------------

### Project Setup with uv and pre-commit

Source: https://github.com/sergioteula/python-amazon-paapi/blob/master/README.md

Instructions for setting up the project locally using the uv package manager and installing pre-commit hooks for automated code quality checks.

```bash
git clone https://github.com/sergioteula/python-amazon-paapi.git
cd python-amazon-paapi
uv sync
uv run pre-commit install
```

--------------------------------

### Install Async Support

Source: https://github.com/sergioteula/python-amazon-paapi/blob/master/docs/amazon_creatorsapi.aio.md

Install the library with asynchronous support using pip. This command ensures that all necessary dependencies for async operations are included.

```bash
pip install python-amazon-paapi[async] --upgrade
```

--------------------------------

### Install python-amazon-paapi

Source: https://github.com/sergioteula/python-amazon-paapi/blob/master/docs/pages/usage-guide.md

Install or upgrade the module using pip. For async support, use the [async] extra.

```bash
pip install python-amazon-paapi --upgrade
```

```bash
pip install python-amazon-paapi[async] --upgrade
```

--------------------------------

### Get Product Information by ASIN

Source: https://github.com/sergioteula/python-amazon-paapi/blob/master/README.md

Retrieve product details using a single ASIN. The ASIN can be passed as a string in a list.

```python
# Get product information by ASIN
items = api.get_items(["B01N5IB20Q"])
print(items[0].item_info.title.display_value)
```

--------------------------------

### Get Items

Source: https://github.com/sergioteula/python-amazon-paapi/blob/master/README.md

Retrieve product information by ASIN or Amazon URL.

```APIDOC
## Get Items

### Description
Retrieve product information for one or more items using their ASINs or Amazon URLs.

### Method
```python
api.get_items(item_ids: list[str]) -> list[Item]
```

### Parameters

- **item_ids** (list[str]) - Required - A list of ASINs or Amazon URLs for the items.

### Request Example
```python
# Get product information by ASIN
items = api.get_items(["B01N5IB20Q"])
print(items[0].item_info.title.display_value)

# Or use Amazon URLs directly
items = api.get_items(["https://www.amazon.com/dp/B01N5IB20Q"])

# Get multiple items
items = api.get_items(["B01N5IB20Q", "B01F9G43WU"])
for item in items:
    print(item.images.primary.large.url)
```

### Response

- **Item** - A list of Item objects containing product information.
```

--------------------------------

### Get Product Information by ASIN

Source: https://github.com/sergioteula/python-amazon-paapi/blob/master/docs/pages/usage-guide.md

Retrieve product details using a list of ASINs. You can also use Amazon product URLs directly.

```python
# Get product information by ASIN
items = api.get_items(["B01N5IB20Q"])
print(items[0].item_info.title.display_value)

# Or use Amazon URLs directly
items = api.get_items(["https://www.amazon.com/dp/B01N5IB20Q"])
```

--------------------------------

### Get Product Information using Amazon URL

Source: https://github.com/sergioteula/python-amazon-paapi/blob/master/README.md

Retrieve product details by providing an Amazon product URL. The URL should be included in a list.

```python
# Or use Amazon URLs directly
items = api.get_items(["https://www.amazon.com/dp/B01N5IB20Q"])
```

--------------------------------

### Get Multiple Items

Source: https://github.com/sergioteula/python-amazon-paapi/blob/master/docs/pages/usage-guide.md

Fetch details for multiple products by providing a list of ASINs or URLs to the `get_items` method.

```python
items = api.get_items(["B01N5IB20Q", "B01F9G43WU"])
for item in items:
    print(item.images.primary.large.url)
```

--------------------------------

### Get Item Details with Specific Resources

Source: https://context7.com/sergioteula/python-amazon-paapi/llms.txt

Retrieve only the title and price for an item to optimize response size and speed. Ensure the necessary resources are specified.

```python
from amazon_creatorsapi import GetItemsResource

items = api.get_items(
    ["B01N5IB20Q"],
    resources=[
        GetItemsResource.ITEMINFO_TITLE,
        GetItemsResource.OFFERS_LISTINGS_PRICE,
        GetItemsResource.OFFERSV2_LISTINGS_PRICE,
        GetItemsResource.IMAGES_PRIMARY_LARGE,
    ],
)
```

--------------------------------

### Get ASIN from URL

Source: https://github.com/sergioteula/python-amazon-paapi/blob/master/README.md

Extract the ASIN from an Amazon product URL.

```APIDOC
## Get ASIN from URL

### Description
Extract the Amazon Standard Identification Number (ASIN) from a given Amazon product URL.

### Method
```python
get_asin(url: str) -> str
```

### Parameters

- **url** (str) - Required - The Amazon product URL.

### Request Example
```python
from amazon_creatorsapi import get_asin

asin = get_asin("https://www.amazon.com/dp/B01N5IB20Q")
```

### Response

- **str** - The extracted ASIN.
```

--------------------------------

### Get Variations

Source: https://github.com/sergioteula/python-amazon-paapi/blob/master/README.md

Retrieve product variations for a given item.

```APIDOC
## Get Variations

### Description
Retrieve product variations (e.g., different sizes, colors) for a given item using its ASIN or Amazon URL.

### Method
```python
api.get_variations(item_id: str) -> VariationsResults
```

### Parameters

- **item_id** (str) - Required - The ASIN or Amazon URL of the item.

### Request Example
```python
# Using ASIN
variations = api.get_variations("B01N5IB20Q")

# Or using Amazon URL
variations = api.get_variations("https://www.amazon.com/dp/B01N5IB20Q")

for item in variations.items:
    print(item.detail_page_url)
```

### Response

- **VariationsResults** - An object containing the variations for the item, including a list of `Item` objects.
```

--------------------------------

### Get Product Variations

Source: https://github.com/sergioteula/python-amazon-paapi/blob/master/docs/pages/usage-guide.md

Retrieve variations for a product using its ASIN or Amazon URL. The response includes a list of related items.

```python
# Using ASIN
variations = api.get_variations("B01N5IB20Q")

# Or using Amazon URL
variations = api.get_variations("https://www.amazon.com/dp/B01N5IB20Q")

for item in variations.items:
    print(item.detail_page_url)
```

--------------------------------

### Get Browse Node Information

Source: https://github.com/sergioteula/python-amazon-paapi/blob/master/docs/pages/usage-guide.md

Fetch details for specific browse nodes using their IDs. The output includes the display name of each node.

```python
nodes = api.get_browse_nodes(["667049031"])
for node in nodes:
    print(node.display_name)
```

--------------------------------

### Using SortBy Enum for Search Ordering

Source: https://github.com/sergioteula/python-amazon-paapi/blob/master/README.md

Shows how to use the SortBy enum to specify the ordering of search results, for example, sorting by price from low to high. Import SortBy from amazon_creatorsapi.models.

```python
from amazon_creatorsapi.models import SortBy

results = api.search_items(keywords="laptop", sort_by=SortBy.PRICE_LOW_TO_HIGH)
```

--------------------------------

### Initialize AsyncAmazonCreatorsApi

Source: https://github.com/sergioteula/python-amazon-paapi/blob/master/docs/pages/usage-guide.md

Set up the asynchronous API client. Using `async with` is recommended for efficient connection management.

```python
from amazon_creatorsapi.aio import AsyncAmazonCreatorsApi
from amazon_creatorsapi import Country

# Use as async context manager (recommended for connection pooling)
async with AsyncAmazonCreatorsApi(
    credential_id="your_credential_id",
    credential_secret="your_credential_secret",
    version="2.2",
    tag="your-affiliate-tag",
    country=Country.US,
) as api:
    # All methods work identically, just use await
    items = await api.get_items(["B01N5IB20Q"])
    results = await api.search_items(keywords="laptop")
    variations = await api.get_variations("B01N5IB20Q")
    nodes = await api.get_browse_nodes(["667049031"])

# Or use without context manager (creates new connection per request)
api = AsyncAmazonCreatorsApi(ID, SECRET, VERSION, TAG, COUNTRY)
items = await api.get_items(["B01N5IB20Q"])
```

--------------------------------

### Initialize AmazonCreatorsApi Client

Source: https://context7.com/sergioteula/python-amazon-paapi/llms.txt

Instantiate the synchronous client with credentials and configuration. Ensure either 'country' or 'marketplace' is provided. Throttling is enforced automatically.

```python
from amazon_creatorsapi import AmazonCreatorsApi, Country
from amazon_creatorsapi.errors import (
    AmazonCreatorsApiError,
    InvalidArgumentError,
    ItemsNotFoundError,
    TooManyRequestsError,
    AssociateValidationError,
    RequestError,
    AuthenticationError,
)

# Initialize the client
api = AmazonCreatorsApi(
    credential_id="YOUR_CREDENTIAL_ID",
    credential_secret="YOUR_CREDENTIAL_SECRET",
    version="2.2",           # API version for your region, e.g. "2.1", "2.2", "3.1"
    tag="yoursite-20",       # Your Amazon affiliate partner tag
    country=Country.US,      # Use Country constants or a raw string like "US"
    throttling=1.0,          # Seconds to wait between calls (default: 1)
)

# Use a direct marketplace URL instead of country (overrides country if both given)
api_es = AmazonCreatorsApi(
    credential_id="YOUR_CREDENTIAL_ID",
    credential_secret="YOUR_CREDENTIAL_SECRET",
    version="2.2",
    tag="yoursite-21",
    marketplace="www.amazon.es",
)

# InvalidArgumentError raised if neither country nor marketplace is given
try:
    bad = AmazonCreatorsApi("id", "secret", "2.2", "tag")
except InvalidArgumentError as e:
    print(f"Config error: {e}")
```

--------------------------------

### Get Browse Nodes

Source: https://github.com/sergioteula/python-amazon-paapi/blob/master/README.md

Retrieve information about Amazon browse nodes.

```APIDOC
## Get Browse Nodes

### Description
Retrieve information about Amazon browse nodes using their IDs.

### Method
```python
api.get_browse_nodes(browse_node_ids: list[str]) -> list[BrowseNode]
```

### Parameters

- **browse_node_ids** (list[str]) - Required - A list of browse node IDs.

### Request Example
```python
nodes = api.get_browse_nodes(["667049031"])
for node in nodes:
    print(node.display_name)
```

### Response

- **BrowseNode** - A list of BrowseNode objects containing information about the specified nodes.
```

--------------------------------

### Fetch Browse Nodes with Python

Source: https://context7.com/sergioteula/python-amazon-paapi/llms.txt

Demonstrates fetching single and multiple browse nodes, navigating ancestor hierarchies, inspecting child nodes, and requesting specific resources or preferred languages. Includes error handling for not found nodes.

```python
from amazon_creatorsapi.resources import GetBrowseNodesResource
from amazon_creatorsapi.errors import ItemsNotFoundError

# Fetch a single browse node
nodes = api.get_browse_nodes(["667049031"])
node = nodes[0]
print(node.id)            # "667049031"
print(node.display_name)  # "Electronics"
print(node.context_free_name)

# Fetch multiple nodes at once
nodes = api.get_browse_nodes(["667049031", "283155", "172282"])
for node in nodes:
    print(node.id, node.display_name)

# Navigate ancestor hierarchy (path to root)
if node.ancestor:
    parent = node.ancestor
    while parent:
        print(f"  Parent: {parent.id} — {parent.display_name}")
        parent = parent.ancestor if hasattr(parent, "ancestor") else None

# Inspect child nodes
if node.children:
    for child in node.children:
        print(f"  Child: {child.id} — {child.display_name}")

# Request specific resources
resources = [
    GetBrowseNodesResource.BROWSENODEINFO_BROWSENODES,
    GetBrowseNodesResource.BROWSENODEINFO_BROWSENODES_ANCESTOR,
    GetBrowseNodesResource.BROWSENODEINFO_BROWSENODES_CHILDREN,
]
nodes = api.get_browse_nodes(["667049031"], resources=resources)

# Request results in a preferred language
nodes = api.get_browse_nodes(["667049031"], languages_of_preference=["fr_FR"])

try:
    nodes = api.get_browse_nodes(["000000000"])
except ItemsNotFoundError:
    print("Browse node not found")
```

--------------------------------

### Initialize AmazonCreatorsApi

Source: https://github.com/sergioteula/python-amazon-paapi/blob/master/docs/amazon_creatorsapi.md

Instantiate the AmazonCreatorsApi class with your credentials and configuration. Ensure either country or marketplace is provided to determine the correct Amazon domain.

```python
>>> api = AmazonCreatorsApi(
...     credential_id="your_id",
...     credential_secret="your_secret",
...     version="2.2",
...     tag="your-tag",
...     country="ES"
... )
>>> items = api.get_items(["B0DLFMFBJW"])
```

--------------------------------

### Initialize AsyncAmazonCreatorsApi

Source: https://github.com/sergioteula/python-amazon-paapi/blob/master/README.md

Initialize the asynchronous API client using 'AsyncAmazonCreatorsApi'. It's recommended to use it as an async context manager for proper connection handling. All methods must be called with 'await'.

```python
from amazon_creatorsapi.aio import AsyncAmazonCreatorsApi
from amazon_creatorsapi import Country

# Use as async context manager (recommended for connection pooling)
async with AsyncAmazonCreatorsApi(
    credential_id="your_credential_id",
    credential_secret="your_credential_secret",
    version="2.2",
    tag="your-affiliate-tag",
    country=Country.US,
) as api:
    items = await api.get_items(["B01N5IB20Q"])
    results = await api.search_items(keywords="laptop")
    variations = await api.get_variations("B01N5IB20Q")
    nodes = await api.get_browse_nodes(["667049031"])
```

--------------------------------

### Upgrade python-amazon-paapi

Source: https://github.com/sergioteula/python-amazon-paapi/blob/master/docs/pages/migration-guide-6.md

Run this command to upgrade to the latest version of the library.

```none
pip install python-amazon-paapi --upgrade
```

--------------------------------

### Initialize API

Source: https://github.com/sergioteula/python-amazon-paapi/blob/master/README.md

Initialize the AmazonCreatorsApi with your credentials and country.

```APIDOC
## Initialize API

### Description
Initialize the AmazonCreatorsApi with your Creators API credentials, version, affiliate tag, and country.

### Method
```python
AmazonCreatorsApi(
    credential_id: str,
    credential_secret: str,
    version: str,
    tag: str,
    country: Country,
    throttling: int = 1
)
```

### Parameters

- **credential_id** (str) - Required - Your Amazon Creators API credential ID.
- **credential_secret** (str) - Required - Your Amazon Creators API credential secret.
- **version** (str) - Required - The API version to use.
- **tag** (str) - Required - Your Amazon affiliate tag.
- **country** (Country) - Required - The Amazon country domain.
- **throttling** (int) - Optional - The wait time in seconds between API calls (default is 1 second).

### Request Example
```python
from amazon_creatorsapi import AmazonCreatorsApi, Country

api = AmazonCreatorsApi(
    credential_id="your_credential_id",
    credential_secret="your_credential_secret",
    version="2.2",
    tag="your-affiliate-tag",
    country=Country.US,
)
```
```

--------------------------------

### AmazonCreatorsApi Initialization

Source: https://context7.com/sergioteula/python-amazon-paapi/llms.txt

Instantiate the synchronous client `AmazonCreatorsApi` with your Amazon API credentials and affiliate tag. You can specify the country or a direct marketplace URL. The client automatically handles authentication, request throttling, and response deserialization.

```APIDOC
## AmazonCreatorsApi — Synchronous Client

The main synchronous client class. Instantiate it once with your credentials and reuse it across calls. Throttling is enforced automatically between requests using `time.sleep`. Provide either `country` (a `Country` constant) or `marketplace` (a direct URL string); at least one is required.

```python
from amazon_creatorsapi import AmazonCreatorsApi, Country
from amazon_creatorsapi.errors import (
    AmazonCreatorsApiError,
    InvalidArgumentError,
    ItemsNotFoundError,
    TooManyRequestsError,
    AssociateValidationError,
    RequestError,
    AuthenticationError,
)

# Initialize the client
api = AmazonCreatorsApi(
    credential_id="YOUR_CREDENTIAL_ID",
    credential_secret="YOUR_CREDENTIAL_SECRET",
    version="2.2",           # API version for your region, e.g. "2.1", "2.2", "3.1"
    tag="yoursite-20",       # Your Amazon affiliate partner tag
    country=Country.US,      # Use Country constants or a raw string like "US"
    throttling=1.0,          # Seconds to wait between calls (default: 1)
)

# Use a direct marketplace URL instead of country (overrides country if both given)
api_es = AmazonCreatorsApi(
    credential_id="YOUR_CREDENTIAL_ID",
    credential_secret="YOUR_CREDENTIAL_SECRET",
    version="2.2",
    tag="yoursite-21",
    marketplace="www.amazon.es",
)

# InvalidArgumentError raised if neither country nor marketplace is given
try:
    bad = AmazonCreatorsApi("id", "secret", "2.2", "tag")
except InvalidArgumentError as e:
    print(f"Config error: {e}")
```
```

--------------------------------

### Initialize AmazonCreatorsApi

Source: https://github.com/sergioteula/python-amazon-paapi/blob/master/docs/pages/usage-guide.md

Initialize the API client with your credentials and country. The Creators API is recommended over the deprecated amazon_paapi module.

```python
from amazon_creatorsapi import AmazonCreatorsApi, Country

api = AmazonCreatorsApi(
    credential_id="your_credential_id",
    credential_secret="your_credential_secret",
    version="2.2",
    tag="your-affiliate-tag",
    country=Country.US,
)
```

--------------------------------

### Fetch Products by ASIN or URL with AmazonCreatorsApi.get_items

Source: https://context7.com/sergioteula/python-amazon-paapi/llms.txt

Retrieves detailed product data for one or more ASINs, Amazon URLs, or comma-separated strings. Supports filtering by condition, requesting specific resources, and setting currency or language preferences.

```python
from amazon_creatorsapi import AmazonCreatorsApi, Country
from amazon_creatorsapi.models import Condition, GetItemsResource
from amazon_creatorsapi.errors import ItemsNotFoundError, InvalidArgumentError

api = AmazonCreatorsApi("CRED_ID", "CRED_SECRET", "2.2", "tag-20", country=Country.US)

# Fetch a single item by ASIN
items = api.get_items(["B01N5IB20Q"])
item = items[0]
print(item.item_info.title.display_value)   # "Nintendo Switch"
print(item.detail_page_url)                  # https://www.amazon.com/dp/B01N5IB20Q
print(item.images.primary.large.url)         # https://m.media-amazon.com/...

# Fetch multiple items at once (up to 10)
items = api.get_items(["B01N5IB20Q", "B01F9G43WU"])
for item in items:
    print(item.asin, item.item_info.title.display_value)

# Accept Amazon URLs directly
items = api.get_items(["https://www.amazon.com/dp/B01N5IB20Q"])

# Accept a comma-separated string
items = api.get_items("B01N5IB20Q,B01F9G43WU")

# Filter by condition (NEW, USED, COLLECTIBLE, REFURBISHED, ANY)
items = api.get_items(["B01N5IB20Q"], condition=Condition.NEW)

# Request only specific resources (reduces response size)
resources = [
    GetItemsResource.ITEMINFO_TITLE,
    GetItemsResource.OFFERS_LISTINGS_PRICE,
    GetItemsResource.IMAGES_PRIMARY_LARGE,
]
items = api.get_items(["B01N5IB20Q"], resources=resources)

# Request prices in a specific currency
items = api.get_items(["B01N5IB20Q"], currency_of_preference="EUR")

# Request content in preferred language
items = api.get_items(["B01N5IB20Q"], languages_of_preference=["en_US", "fr_FR"])

# Access OffersV2 pricing data
if item.offers_v2 and item.offers_v2.listings:
    listing = item.offers_v2.listings[0]
    print(listing.price.money.amount)         # e.g. 29.99
    print(listing.price.money.currency)       # "USD"
    print(listing.merchant_info.name)         # "Amazon.com"
    if listing.saving_basis:
        print(listing.saving_basis.amount)    # original price
```

--------------------------------

### Async API Initialization and Item Retrieval

Source: https://github.com/sergioteula/python-amazon-paapi/blob/master/README.md

Initialize the asynchronous API client without a context manager for individual requests. This method creates a new connection for each API call.

```python
api = AsyncAmazonCreatorsApi(ID, SECRET, VERSION, TAG, COUNTRY)
items = await api.get_items(["B01N5IB20Q"])
```

--------------------------------

### Access OffersV2 Details

Source: https://github.com/sergioteula/python-amazon-paapi/blob/master/docs/pages/usage-guide.md

Retrieve enhanced pricing and offer details using the OffersV2 resource. This includes price amount and merchant name.

```python
items = api.get_items(["B01N5IB20Q"])
item = items[0]
if item.offers_v2 and item.offers_v2.listings:
    listing = item.offers_v2.listings[0]
    print(listing.price.money.amount)
    print(listing.merchant_info.name)
```

--------------------------------

### Importing models

Source: https://github.com/sergioteula/python-amazon-paapi/blob/master/docs/pages/migration-guide-6.md

Import SDK models directly from the models module for convenient access.

```python
from amazon_creatorsapi.models import (
    Item,
    Condition,
    SortBy,
    GetItemsResource,
    SearchItemsResource,
    GetVariationsResource,
    GetBrowseNodesResource,
)
```

--------------------------------

### ProductInfo Model

Source: https://github.com/sergioteula/python-amazon-paapi/blob/master/docs/amazon_creatorsapi.models.md

Represents product information. Provides methods to create instances from dictionaries or JSON strings, and to convert instances back to dictionaries or JSON strings.

```APIDOC
## ProductInfo Class

### Description
Represents product information.

### Methods
#### `from_dict(obj)`
Create an instance of ProductInfo from a dict.

#### `from_json(json_str)`
Create an instance of ProductInfo from a JSON string.

#### `to_dict()`
Return the dictionary representation of the model using alias.

#### `to_json()`
Returns the JSON representation of the model using alias.

#### `to_str()`
Returns the string representation of the model using alias.

### Attributes
- `is_adult_product`
- `item_dimensions`
- `release_date`
- `size`
- `unit_count`
```

--------------------------------

### Search Products by Keywords

Source: https://github.com/sergioteula/python-amazon-paapi/blob/master/docs/pages/usage-guide.md

Search for products using keywords. The results contain a list of items with their details.

```python
results = api.search_items(keywords="nintendo switch")
for item in results.items:
    print(item.item_info.title.display_value)
```

--------------------------------

### OfferListingV2 Model

Source: https://github.com/sergioteula/python-amazon-paapi/blob/master/docs/amazon_creatorsapi.models.md

Details various offer listings associated with a product. Includes availability, condition, deal information, price, and merchant details. Provides methods for instantiation and data conversion.

```APIDOC
## OfferListingV2

### Description
Specifies about various offer listings associated with the product.

### Methods
#### `from_dict(obj: dict) -> OfferListingV2`
Create an instance of OfferListingV2 from a dictionary.

#### `from_json(json_str: str) -> OfferListingV2`
Create an instance of OfferListingV2 from a JSON string.

#### `to_dict() -> dict`
Return the dictionary representation of the model.

#### `to_json() -> str`
Returns the JSON representation of the model.

#### `to_str() -> str`
Returns the string representation of the model.

### Properties
- `availability` (Availability, optional): Availability status of the offer.
- `condition` (OfferConditionV2, optional): The condition of the offer.
- `deal_details` (DealDetails, optional): Details about any deals associated with the offer.
- `is_buy_box_winner` (bool, optional): Indicates if this offer is the Buy Box winner.
- `loyalty_points` (OfferLoyaltyPointsV2, optional): Loyalty points associated with the offer.
- `merchant_info` (OfferMerchantInfoV2, optional): Information about the merchant offering the product.
- `price` (OfferPriceV2, optional): The price details of the offer.
- `type` (str, optional): The type of the offer listing.
- `violates_map` (bool, optional): Indicates if the offer violates MAP (Minimum Advertised Price) policies.
```

--------------------------------

### Helper function import changes

Source: https://github.com/sergioteula/python-amazon-paapi/blob/master/docs/pages/migration-guide-6.md

Update import paths for helper functions like get_asin.

```diff
- from amazon_paapi import get_asin
+ from amazon_creatorsapi.core import get_asin
```

--------------------------------

### Initialize AmazonCreatorsApi

Source: https://github.com/sergioteula/python-amazon-paapi/blob/master/README.md

Initialize the API client with your Amazon Creators API credentials and desired country. This client can be used for synchronous API calls.

```python
from amazon_creatorsapi import AmazonCreatorsApi, Country

# Initialize with your Creators API credentials
api = AmazonCreatorsApi(
    credential_id="your_credential_id",
    credential_secret="your_credential_secret",
    version="2.2",
    tag="your-affiliate-tag",
    country=Country.US,
)
```

--------------------------------

### Async Support

Source: https://github.com/sergioteula/python-amazon-paapi/blob/master/README.md

Use the asynchronous version of the API for async/await applications.

```APIDOC
## Async Support

### Description
For asynchronous applications, use the `AsyncAmazonCreatorsApi` class. This requires installing the `httpx` library.

### Installation
```bash
pip install python-amazon-paapi[async] --upgrade
```

### Usage
The async API provides the same methods as the synchronous version, but they must be called with `await` and used within an async context manager.

### Request Example
```python
from amazon_creatorsapi.aio import AsyncAmazonCreatorsApi
from amazon_creatorsapi import Country

async with AsyncAmazonCreatorsApi(
    credential_id="your_credential_id",
    credential_secret="your_credential_secret",
    version="2.2",
    tag="your-affiliate-tag",
    country=Country.US,
) as api:
    items = await api.get_items(["B01N5IB20Q"])
    results = await api.search_items(keywords="laptop")
    variations = await api.get_variations("B01N5IB20Q")
    nodes = await api.get_browse_nodes(["667049031"])
```
```

--------------------------------

### Use SDK Models for Filtering and Resources

Source: https://github.com/sergioteula/python-amazon-paapi/blob/master/docs/pages/usage-guide.md

Import and utilize enums and resource types from `amazon_creatorsapi.models` for precise filtering and data retrieval.

```python
from amazon_creatorsapi.models import (
    Item,
    Condition,
    SortBy,
    GetItemsResource,
    SearchItemsResource,
)

# Use Condition enum for filtering
items = api.get_items(["B01N5IB20Q"], condition=Condition.NEW)

# Use SortBy enum for search ordering
results = api.search_items(keywords="laptop", sort_by=SortBy.PRICE_LOW_TO_HIGH)

# Specify which resources to retrieve
from amazon_creatorsapi.models import GetItemsResource
resources = [GetItemsResource.ITEMINFO_TITLE, GetItemsResource.OFFERS_LISTINGS_PRICE]
items = api.get_items(["B01N5IB20Q"], resources=resources)
```

--------------------------------

### DealDetails Model

Source: https://github.com/sergioteula/python-amazon-paapi/blob/master/docs/amazon_creatorsapi.models.md

Provides details about a product's deal, including access type, badge, duration, and start/end times. Supports conversion to and from dictionary and JSON formats.

```APIDOC
## class amazon_creatorsapi.models.DealDetails

### Description
Specifies deal information about an offer.

### Methods
- **to_dict()**: Return the dictionary representation of the model using alias.
- **to_json()**: Returns the JSON representation of the model using alias.
- **to_str()**: Returns the string representation of the model using alias.
- **from_dict(obj)**: Create an instance of DealDetails from a dict.
- **from_json(json_str)**: Create an instance of DealDetails from a JSON string

### Attributes
- **access_type**
- **badge**
- **early_access_duration_in_milliseconds**
- **end_time**
- **percent_claimed**
- **start_time**
```

--------------------------------

### Search Items with Filters and Sorting

Source: https://context7.com/sergioteula/python-amazon-paapi/llms.txt

Search for products using keywords, condition filters, and sorting options. Specify required resources for the search results.

```python
from amazon_creatorsapi import Condition, SortBy, SearchItemsResource

result = api.search_items(
    keywords="mechanical keyboard",
    condition=Condition.NEW,
    sort_by=SortBy.PRICE_LOW_TO_HIGH,
    resources=[
        SearchItemsResource.ITEMINFO_TITLE,
        SearchItemsResource.OFFERS_LISTINGS_PRICE,
    ],
)
```

--------------------------------

### Handle No Results Found Error in Product Search

Source: https://context7.com/sergioteula/python-amazon-paapi/llms.txt

Demonstrates catching the ItemsNotFoundError exception when a product search yields no results. This is a common scenario for searches with very specific or non-existent keywords.

```python
try:
    result = api.search_items(keywords="zzznoresults12345xyz")
except ItemsNotFoundError:
    print("No results found")
```

--------------------------------

### Specifying Resources for Item Retrieval

Source: https://github.com/sergioteula/python-amazon-paapi/blob/master/README.md

Illustrates how to specify which resources to retrieve for items using the GetItemsResource enum. Import GetItemsResource from amazon_creatorsapi.models.

```python
from amazon_creatorsapi.models import GetItemsResource

resources = [GetItemsResource.ITEMINFO_TITLE, GetItemsResource.OFFERS_LISTINGS_PRICE]
items = api.get_items(["B01N5IB20Q"], resources=resources)
```

--------------------------------

### Fetch Product Variations by ASIN with Amazon PA-API

Source: https://context7.com/sergioteula/python-amazon-paapi/llms.txt

Retrieves all variants of a product, such as different sizes or colors, using its ASIN. The response includes variation summary and details for each item. Requires initialization of AmazonCreatorsApi.

```python
from amazon_creatorsapi import AmazonCreatorsApi, Country
from amazon_creatorsapi.models import Condition, GetVariationsResource
from amazon_creatorsapi.errors import ItemsNotFoundError

api = AmazonCreatorsApi("CRED_ID", "CRED_SECRET", "2.2", "tag-20", country=Country.US)

# Fetch all variations by ASIN
result = api.get_variations("B01N5IB20Q")
print(result.variation_summary.variation_count)  # Total variants

for item in result.items:
    print(item.asin)
    print(item.detail_page_url)
    # Access variation-specific attribute values
    if item.item_info and item.item_info.classifications:
        print(item.item_info.classifications.product_group.display_value)
```

--------------------------------

### Initialization changes

Source: https://github.com/sergioteula/python-amazon-paapi/blob/master/docs/pages/migration-guide-6.md

Modify the initialization of the API client to use new credential parameters and the version number.

```diff
- amazon = AmazonApi(
-     access_key="YOUR_ACCESS_KEY",
-     secret_key="YOUR_SECRET_KEY",
-     partner_tag="YOUR_TAG",
-     country="ES"
- )
-
+ amazon = AmazonCreatorsApi(
+     credential_id="YOUR_CREDENTIAL_ID",
+     credential_secret="YOUR_CREDENTIAL_SECRET",
+     version="2.2",
+     tag="YOUR_TAG",
+     country="ES"
+ )
```

--------------------------------

### RefinementBin Model

Source: https://github.com/sergioteula/python-amazon-paapi/blob/master/docs/amazon_creatorsapi.models.md

Represents a bin containing values for a specific refinement.

```APIDOC
## RefinementBin Class

### Description
Container for a refinement bin which contains values for a particular refinement.

### Methods
#### `from_dict(obj)`
Create an instance of RefinementBin from a dict.

#### `from_json(json_str)`
Create an instance of RefinementBin from a JSON string.

#### `to_dict()`
Return the dictionary representation of the model using alias.

#### `to_json()`
Returns the JSON representation of the model using alias.

#### `to_str()`
Returns the string representation of the model using alias.

### Attributes
- `display_name`
- `id`
```

--------------------------------

### Configure API Throttling Settings

Source: https://context7.com/sergioteula/python-amazon-paapi/llms.txt

Instantiate the AmazonCreatorsApi with different throttling settings, from conservative (e.g., 4 seconds delay) to aggressive (no delay). Throttling can also be adjusted dynamically at runtime.

```python
from amazon_creatorsapi import AmazonCreatorsApi, Country

# Conservative throttling for shared credentials (1 call per 4 seconds)
api_safe = AmazonCreatorsApi("id", "secret", "2.2", "tag", country=Country.US, throttling=4)

# Aggressive (no throttling — use only for single requests or testing)
api_fast = AmazonCreatorsApi("id", "secret", "2.2", "tag", country=Country.US, throttling=0)

# Default (1 second between calls)
api = AmazonCreatorsApi("id", "secret", "2.2", "tag", country=Country.US)

# Dynamic adjustment at runtime
api.throttling = 2.0
```

--------------------------------

### OfferPriceV2 Model

Source: https://github.com/sergioteula/python-amazon-paapi/blob/master/docs/amazon_creatorsapi.models.md

Details the buying price of an offer, including monetary value, price per unit, and savings information. Supports instantiation from dictionaries or JSON strings and conversion to dictionary or JSON string.

```APIDOC
## OfferPriceV2

### Description
Specifies buying price of an offer.

### Methods
#### `from_dict(obj: dict) -> OfferPriceV2`
Create an instance of OfferPriceV2 from a dictionary.

#### `from_json(json_str: str) -> OfferPriceV2`
Create an instance of OfferPriceV2 from a JSON string.

#### `to_dict() -> dict`
Return the dictionary representation of the model.

#### `to_json() -> str`
Returns the JSON representation of the model.

#### `to_str() -> str`
Returns the string representation of the model.

### Properties
- `money` (Money, optional): The monetary value of the price.
- `price_per_unit` (PricePerUnit, optional): The price per unit of the item.
- `savings` (Savings, optional): Information about any savings or discounts.
- `saving_basis` (str, optional): The basis for the saving calculation.
```

--------------------------------

### AmazonCreatorsApi.get_items

Source: https://context7.com/sergioteula/python-amazon-paapi/llms.txt

Retrieves detailed product data for one or more ASINs, Amazon product URLs, or comma-separated ASIN strings. You can filter results by condition, request specific resources to reduce response size, specify currency preference, and set preferred languages.

```APIDOC
## `AmazonCreatorsApi.get_items` — Fetch Products by ASIN or URL

Retrieves detailed product data for one or more ASINs. Accepts raw ASINs, full Amazon product URLs, or comma-separated strings. Returns a `list[Item]` with all available fields populated by default.

```python
from amazon_creatorsapi import AmazonCreatorsApi, Country
from amazon_creatorsapi.models import Condition, GetItemsResource
from amazon_creatorsapi.errors import ItemsNotFoundError, InvalidArgumentError

api = AmazonCreatorsApi("CRED_ID", "CRED_SECRET", "2.2", "tag-20", country=Country.US)

# Fetch a single item by ASIN
items = api.get_items(["B01N5IB20Q"])
item = items[0]
print(item.item_info.title.display_value)   # "Nintendo Switch"
print(item.detail_page_url)                  # https://www.amazon.com/dp/B01N5IB20Q
print(item.images.primary.large.url)         # https://m.media-amazon.com/...

# Fetch multiple items at once (up to 10)
items = api.get_items(["B01N5IB20Q", "B01F9G43WU"])
for item in items:
    print(item.asin, item.item_info.title.display_value)

# Accept Amazon URLs directly
items = api.get_items(["https://www.amazon.com/dp/B01N5IB20Q"])

# Accept a comma-separated string
items = api.get_items("B01N5IB20Q,B01F9G43WU")

# Filter by condition (NEW, USED, COLLECTIBLE, REFURBISHED, ANY)
items = api.get_items(["B01N5IB20Q"], condition=Condition.NEW)

# Request only specific resources (reduces response size)
resources = [
    GetItemsResource.ITEMINFO_TITLE,
    GetItemsResource.OFFERS_LISTINGS_PRICE,
    GetItemsResource.IMAGES_PRIMARY_LARGE,
]
items = api.get_items(["B01N5IB20Q"], resources=resources)

# Request prices in a specific currency
items = api.get_items(["B01N5IB20Q"], currency_of_preference="EUR")

# Request content in preferred language
items = api.get_items(["B01N5IB20Q"], languages_of_preference=["en_US", "fr_FR"])

# Access OffersV2 pricing data
if item.offers_v2 and item.offers_v2.listings:
    listing = item.offers_v2.listings[0]
    print(listing.price.money.amount)         # e.g. 29.99
    print(listing.price.money.currency)       # "USD"
    print(listing.merchant_info.name)         # "Amazon.com"
    if listing.saving_basis:
        print(listing.saving_basis.amount)    # original price
```
```

--------------------------------

### BrowseNode Model

Source: https://github.com/sergioteula/python-amazon-paapi/blob/master/docs/amazon_creatorsapi.models.md

Container for BrowseNode information.

```APIDOC
## Class BrowseNode

Bases: `BaseModel`

Container for BrowseNode information which includes BrowseNodeId, DisplayName, ContextFreeName, IsRoot, Ancestor, Children, SalesRank associated, etc.

### Fields
- **ancestor**: (type not specified) - Description not specified
- **children**: (type not specified) - Description not specified
- **context_free_name**: (type not specified) - Description not specified
- **display_name**: (type not specified) - Description not specified
- **id**: (type not specified) - Description not specified
- **is_root**: (type not specified) - Description not specified
- **sales_rank**: (type not specified) - Description not specified

### Class Methods
#### from_dict(obj)
Create an instance of BrowseNode from a dict

#### from_json(json_str)
Create an instance of BrowseNode from a JSON string

### Methods
#### to_dict()
Return the dictionary representation of the model using alias.

#### to_json()
Returns the JSON representation of the model using alias

#### to_str()
Returns the string representation of the model using alias
```

--------------------------------

### Handle No Variations Found Error

Source: https://context7.com/sergioteula/python-amazon-paapi/llms.txt

Demonstrates catching the `ItemsNotFoundError` when a product has no variations or the provided ASIN is invalid. This ensures graceful handling of cases where variation data is unavailable.

```python
try:
    result = api.get_variations("B000000000")
except ItemsNotFoundError:
    print("No variations found for this product")
```

--------------------------------

### OfferMerchantInfoV2 Model

Source: https://github.com/sergioteula/python-amazon-paapi/blob/master/docs/amazon_creatorsapi.models.md

Provides information about the seller of an offer. Includes merchant name and ID. Offers methods for creating instances and converting to dictionary or JSON string.

```APIDOC
## OfferMerchantInfoV2

### Description
Specifies seller information of an offer.

### Methods
#### `from_dict(obj: dict) -> OfferMerchantInfoV2`
Create an instance of OfferMerchantInfoV2 from a dictionary.

#### `from_json(json_str: str) -> OfferMerchantInfoV2`
Create an instance of OfferMerchantInfoV2 from a JSON string.

#### `to_dict() -> dict`
Return the dictionary representation of the model.

#### `to_json() -> str`
Returns the JSON representation of the model.

#### `to_str() -> str`
Returns the string representation of the model.

### Properties
- `name` (str, optional): The name of the merchant.
- `id` (str, optional): The ID of the merchant.
```

--------------------------------

### Fetch Product Variations using Amazon URL

Source: https://context7.com/sergioteula/python-amazon-paapi/llms.txt

Retrieves product variations by providing a full Amazon product URL instead of an ASIN. This offers flexibility in how product identifiers are supplied.

```python
# Accept full Amazon URL
result = api.get_variations("https://www.amazon.com/dp/B01N5IB20Q")
```

--------------------------------

### ByLineInfo Model

Source: https://github.com/sergioteula/python-amazon-paapi/blob/master/docs/amazon_creatorsapi.models.md

Provides basic product information such as brand, manufacturer, and contributors.

```APIDOC
## ByLineInfo

### Description
Container for set of attributes that specifies basic information of the product like Brand, Manufacturer, etc.

### Attributes
- **brand**: (str) The brand of the product.
- **contributors**: (list) A list of contributors for the product.
- **manufacturer**: (str) The manufacturer of the product.

### Methods
- **from_dict(obj)**: Create an instance of ByLineInfo from a dict.
- **from_json(json_str)**: Create an instance of ByLineInfo from a JSON string.
- **to_dict()**: Return the dictionary representation of the model.
- **to_json()**: Returns the JSON representation of the model.
- **to_str()**: Returns the string representation of the model.
```

--------------------------------

### get_items

Source: https://github.com/sergioteula/python-amazon-paapi/blob/master/docs/amazon_creatorsapi.md

Fetches detailed information about specific items on Amazon using their ASINs or product URLs. Supports filtering by condition and specifying preferred currency and language.

```APIDOC
## get_items(items, condition=None, currency_of_preference=None, languages_of_preference=None, resources=None)

### Description
Get items information from Amazon.

### Parameters
#### Path Parameters
- **items** (str or List[str]) - Required - One or more items, using ASIN or Amazon product URL. Accepts a single string (comma-separated) or a list of strings.
- **condition** (str) - Optional - Filter offers by condition type.
- **currency_of_preference** (str) - Optional - ISO 4217 currency code for prices.
- **languages_of_preference** (List[str]) - Optional - Languages in order of preference.
- **resources** (List[str]) - Optional - List of resources to retrieve. Defaults to all.

### Returns
List of Item objects with Amazon information.

### Raises
- ItemsNotFoundError: If no items are found.
- InvalidArgumentError: If parameters are invalid.
```

--------------------------------

### Handle API Errors with Python

Source: https://context7.com/sergioteula/python-amazon-paapi/llms.txt

Demonstrates how to catch specific exceptions like ItemsNotFoundError and InvalidArgumentError when interacting with the Amazon PA-API.

```python
try:
    items = api.get_items(["INVALIDASIN1"])
except ItemsNotFoundError:
    print("No items found for those ASINs")
except InvalidArgumentError as e:
    print(f"Bad input: {e}")
```

--------------------------------

### AsyncAmazonCreatorsApi

Source: https://context7.com/sergioteula/python-amazon-paapi/llms.txt

Provides an asynchronous client for the Amazon PA-API, mirroring the functionality of the synchronous client but designed for non-blocking I/O operations using `httpx`.

```APIDOC
## AsyncAmazonCreatorsApi

### Description
An asynchronous client for the Amazon Product Advertising API, built using `httpx`. It offers the same methods as the synchronous `AmazonCreatorsApi` but allows for concurrent operations and non-blocking requests. It is recommended to use this client as an asynchronous context manager (`async with`) to benefit from connection pooling.

### Installation
`pip install python-amazon-paapi[async]`

### Initialization
```python
from amazon_creatorsapi.aio import AsyncAmazonCreatorsApi
from amazon_creatorsapi import Country

# Recommended: use as context manager for connection pooling
async with AsyncAmazonCreatorsApi(
    credential_id="YOUR_CREDENTIAL_ID",
    credential_secret="YOUR_CREDENTIAL_SECRET",
    version="2.2",
    tag="yoursite-20",
    country=Country.US,
    throttling=1.0,
) as api:
    # Use API methods here
    pass

# Without context manager: creates a new connection per request
api = AsyncAmazonCreatorsApi("CRED_ID", "CRED_SECRET", "2.2", "tag-20", country=Country.US)
```

### Supported API Methods (asynchronous versions)
- `await api.get_items(item_ids: list[str])`
- `await api.search_items(...)`
- `await api.get_variations(asin: str, ...)`
- `await api.get_browse_nodes(node_ids: list[str], ...)`

### Concurrency Example
```python
import asyncio

async def main():
    async with AsyncAmazonCreatorsApi(...) as api:
        # Run multiple requests concurrently
        items_a, items_b = await asyncio.gather(
            api.get_items(["B01N5IB20Q"]),
            api.get_items(["B01F9G43WU"]),
        )
```

### Version Validation
Raises `ValueError` if an unsupported API version is provided during initialization.
```python
try:
    bad_api = AsyncAmazonCreatorsApi("id", "secret", "9.9", "tag", country=Country.US)
except ValueError as e:
    print(f"Unsupported version: {e}")
    # Supported versions: 2.1, 2.2, 2.3, 3.1, 3.2, 3.3
```

### Error Handling
- Raises `AuthenticationError` for invalid credentials or OAuth2 failures.
- Raises `ItemsNotFoundError` for invalid item IDs or browse nodes.
```
```

--------------------------------

### OfferLoyaltyPointsV2 Model

Source: https://github.com/sergioteula/python-amazon-paapi/blob/master/docs/amazon_creatorsapi.models.md

Represents loyalty points for an offer, primarily for the JP marketplace. Includes methods for instantiation from dictionaries or JSON strings, and conversion to dictionary or JSON string.

```APIDOC
## OfferLoyaltyPointsV2

### Description
Specifies loyalty points in any region against an offer. Right now, only supporting JP marketplace.

### Methods
#### `from_dict(obj: dict) -> OfferLoyaltyPointsV2`
Create an instance of OfferLoyaltyPointsV2 from a dictionary.

#### `from_json(json_str: str) -> OfferLoyaltyPointsV2`
Create an instance of OfferLoyaltyPointsV2 from a JSON string.

#### `to_dict() -> dict`
Return the dictionary representation of the model.

#### `to_json() -> str`
Returns the JSON representation of the model.

#### `to_str() -> str`
Returns the string representation of the model.

### Properties
- `points` (int, optional): The number of loyalty points.
```

--------------------------------

### Search Products by Keyword with Amazon PA-API

Source: https://context7.com/sergioteula/python-amazon-paapi/llms.txt

Performs a basic keyword search for products. Requires initialization of AmazonCreatorsApi with credentials and country. Accesses the total result count and item titles from the search result.

```python
from amazon_creatorsapi import AmazonCreatorsApi, Country
from amazon_creatorsapi.models import Condition, SortBy, SearchItemsResource
from amazon_creatorsapi.errors import ItemsNotFoundError

api = AmazonCreatorsApi("CRED_ID", "CRED_SECRET", "2.2", "tag-20", country=Country.US)

# Basic keyword search
result = api.search_items(keywords="nintendo switch")
print(result.total_result_count)  # Total matches
for item in result.items:
    print(item.item_info.title.display_value)
```

--------------------------------

### Importing PA-API Models and Enums

Source: https://context7.com/sergioteula/python-amazon-paapi/llms.txt

Import resource enums and data model classes from `amazon_creatorsapi.models` to control API response fields and utilize data structures.

```python
from amazon_creatorsapi.models import (
    GetItemsResource,
    SearchItemsResource,
    GetVariationsResource,
    GetBrowseNodesResource,
    Condition,
    SortBy,
    Item,
    ItemInfo,
    Images,
    ImageType,
    ImageSize,
    OffersV2,
    OfferListingV2,
    OfferPriceV2,
    Money,
    SearchResult,
    SearchRefinements,
    VariationsResult,
    VariationSummary,
    VariationDimension,
    BrowseNode,
    BrowseNodeAncestor,
    BrowseNodeChild,
    Condition,
    Availability,
    CustomerReviews,
)
from amazon_creatorsapi import AmazonCreatorsApi, Country

api = AmazonCreatorsApi("CRED_ID", "CRED_SECRET", "2.2", "tag-20", country=Country.US)
```