Merge pull request #142 from sergioteula/add-creators-api-compatibility

Add Amazon Creators API Compatibility

Author: sergioteula

.env.template

@@ -1,4 +1,13 @@
+# Product Advertising API
 API_KEY=
 API_SECRET=
+
+# Creators API
+CREDENTIAL_ID=
+CREDENTIAL_SECRET=
+API_VERSION=
+MARKETPLACE=
+
+# Common
 AFFILIATE_TAG=
 COUNTRY_CODE=

.github/workflows/check.yml

@@ -74,7 +74,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13", "3.14", "3.15"]
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13", "3.14"]
 
     steps:
       - uses: actions/checkout@v5

.pre-commit-config.yaml

@@ -15,7 +15,9 @@ repos:
     rev: v6.0.0
     hooks:
       - id: trailing-whitespace
+        exclude: ^creatorsapi_python_sdk/
       - id: end-of-file-fixer
+        exclude: ^creatorsapi_python_sdk/
       - id: mixed-line-ending
       - id: check-yaml
       - id: check-added-large-files
@@ -38,18 +40,19 @@ repos:
     hooks:
       - id: gitleaks
 
-  - repo: https://github.com/pre-commit/mirrors-mypy
-    rev: "v1.19.1"
+  - repo: local
     hooks:
       - id: mypy
-        exclude: sdk/
+        name: checking types with mypy
+        entry: uv run mypy .
+        language: system
+        types: [python]
+        pass_filenames: false
 
-  - repo: local
-    hooks:
       - id: test
         name: Running tests
         language: system
-        entry: "bash -c 'set -a && source .env 2>/dev/null; set +a && uv run pytest -rs --cov=amazon_paapi'"
+        entry: "bash -c 'set -a && source .env 2>/dev/null; set +a && uv run pytest -rs --cov=amazon_paapi --cov=amazon_creatorsapi'"
         types_or: [python]
         pass_filenames: false
 

CHANGELOG.md

@@ -5,6 +5,33 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [6.0.0] - 2026-01-29
+
+### Added
+
+- New `amazon_creatorsapi` module for Amazon Creators API support
+- `creatorsapi_python_sdk` package bundled for OAuth2 authentication
+- `models` submodule exposing all SDK model classes (Item, Condition, SortBy, etc.)
+- Migration guide from PAAPI to Creators API (`docs/pages/migration-guide-6.md`)
+- Integration tests for the new Creators API module
+- New dependencies: `pydantic>=2.0.0` and `requests>=2.28.0`
+
+### Changed
+
+- **BREAKING**: The `amazon_paapi` module is now deprecated in favor of `amazon_creatorsapi`
+- Updated documentation to reflect the new Creators API module
+- Reorganized utility functions into `amazon_creatorsapi.core` package
+- Updated README with Creators API examples and deprecation notice
+
+### Deprecated
+
+- `amazon_paapi` module - use `amazon_creatorsapi` instead
+- All PAAPI-specific documentation pages removed
+
+### Removed
+
+- Migration guides for versions 4 and 5 (`migration-guide-4.md`, `migration-guide-5.md`)
+
 ## [5.2.0] - 2026-01-11
 
 ### Added

Makefile

@@ -1,7 +1,7 @@
 export UID:=$(shell id -u)
 export GID:=$(shell id -g)
 
-export PYTHON_TAGS = 3.9 3.10 3.11 3.12 3.13 3.14 3.15
+export PYTHON_TAGS = 3.9 3.10 3.11 3.12 3.13 3.14
 
 setup:
 	@uv run pre-commit install
@@ -11,7 +11,7 @@ test:
 	@uv run --env-file .env pytest -rs
 
 coverage:
-	@uv run pytest -rs --cov=amazon_paapi --cov-report=html --cov-report=term --cov-report=xml
+	@uv run pytest -rs --cov=amazon_paapi --cov=amazon_creatorsapi --cov-report=html --cov-report=term --cov-report=xml
 
 test-all-python-tags:
 	@touch .env
@@ -22,6 +22,9 @@ test-all-python-tags:
 lint:
 	@uv run ruff check --fix .
 
+format:
+	@uv run ruff format .
+
 mypy:
 	@uv run mypy .
 

README.md

@@ -1,22 +1,23 @@
-# Python Amazon PAAPI
+# Python Amazon Creators API
 
-A simple Python wrapper for the [Amazon Product Advertising API 5.0](https://webservices.amazon.com/paapi5/documentation/). Easily interact with Amazon's official API to retrieve product information, search for items, and more.
+A Python wrapper for Amazon's product APIs. This package supports both the legacy [Product Advertising API 5.0](https://webservices.amazon.com/paapi5/documentation/) and the new [Amazon Creators API](https://webservices.amazon.com/creatorsapi/documentation/).
 
 [![PyPI](https://img.shields.io/pypi/v/python-amazon-paapi?color=%231182C2&label=PyPI)](https://pypi.org/project/python-amazon-paapi/)
 [![Python](https://img.shields.io/badge/Python-≥3.9-%23FFD140)](https://www.python.org/)
 [![License](https://img.shields.io/badge/License-MIT-%23e83633)](https://github.com/sergioteula/python-amazon-paapi/blob/master/LICENSE)
-[![Amazon API](https://img.shields.io/badge/Amazon%20API-5.0-%23FD9B15)](https://webservices.amazon.com/paapi5/documentation/)
 [![Downloads](https://img.shields.io/pypi/dm/python-amazon-paapi?label=Downloads)](https://pypi.org/project/python-amazon-paapi/)
 
+> [!IMPORTANT]
+> **Migration Advisory**: The `amazon_paapi` module is deprecated. Amazon is transitioning from the Product Advertising API (PAAPI) to the new **Creators API**. Please migrate to the `amazon_creatorsapi` module for new projects. See the [Migration Guide](https://python-amazon-paapi.readthedocs.io/en/latest/pages/migration-guide-6.html) for more information.
+
 ## Features
 
 - 🎯 **Simple object-oriented interface** for easy integration
 - 🔍 **Product search** by keywords, categories, or browse nodes
 - 📦 **Product details** via ASIN or Amazon URL
 - 🔄 **Item variations** support (size, color, etc.)
 - 💰 **OffersV2 support** for enhanced pricing and offer details
-- 🌍 **20+ countries** supported ([full list](https://github.com/sergioteula/python-amazon-paapi/blob/master/amazon_paapi/models/regions.py))
-- ⚡ **Batch requests** to get multiple items without the 10-item limit
+- 🌍 **20+ countries** supported
 - 🛡️ **Built-in throttling** to avoid API rate limits
 - 📝 **Full type hints** for better IDE support
 
@@ -26,93 +27,124 @@ A simple Python wrapper for the [Amazon Product Advertising API 5.0](https://web
 pip install python-amazon-paapi --upgrade
 ```
 
+---
+
 ## Quick Start
 
 ```python
-from amazon_paapi import AmazonApi
+from amazon_creatorsapi import AmazonCreatorsApi, Country
 
-# Initialize the API (get credentials from Amazon Associates)
-amazon = AmazonApi(KEY, SECRET, TAG, 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,
+)
 
 # Get product information by ASIN
-item = amazon.get_items('B01N5IB20Q')[0]
-print(item.item_info.title.display_value)
+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"])
 ```
 
 ## Usage Examples
 
-### Using OffersV2 resources
-
-OffersV2 provides enhanced pricing and offer details. All resources are included by default, so OffersV2 data is available without any additional configuration:
-
-```python
-item = amazon.get_items('B01N5IB20Q')[0]
-if item.offers_v2 and item.offers_v2.listings:
-    listing = item.offers_v2.listings[0]
-    print(listing.price.money.amount)  # Price amount
-    print(listing.merchant_info.name)  # Merchant name
-```
-
-### Get Multiple Products
+### Get Multiple Items
 
 ```python
-items = amazon.get_items(['B01N5IB20Q', 'B01F9G43WU'])
+items = api.get_items(["B01N5IB20Q", "B01F9G43WU"])
 for item in items:
     print(item.images.primary.large.url)
-    print(item.offers.listings[0].price.amount)
-```
-
-### Use Amazon URL Instead of ASIN
-
-```python
-item = amazon.get_items('https://www.amazon.com/dp/B01N5IB20Q')
 ```
 
 ### Search Products
 
 ```python
-results = amazon.search_items(keywords='nintendo switch')
+results = api.search_items(keywords="nintendo switch")
 for item in results.items:
     print(item.item_info.title.display_value)
 ```
 
 ### Get Product Variations
 
 ```python
-variations = amazon.get_variations('B01N5IB20Q')
+# 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
 
 ```python
-nodes = amazon.get_browse_nodes(['667049031', '599385031'])
+nodes = api.get_browse_nodes(["667049031"])
 for node in nodes:
     print(node.display_name)
 ```
 
-### Extract ASIN from URL
+### Get the ASIN from URL
 
 ```python
-from amazon_paapi import get_asin
+from amazon_creatorsapi import get_asin
 
-asin = get_asin('https://www.amazon.com/dp/B01N5IB20Q')
-# Returns: 'B01N5IB20Q'
+asin = get_asin("https://www.amazon.com/dp/B01N5IB20Q")
 ```
 
-### Configure Throttling
+### Using OffersV2 Resources
+
+```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)
+```
 
-Control the wait time between API calls to avoid rate limits:
+### Throttling
+
+Throttling value represents the wait time in seconds between API calls, being the default value 1 second. Use it to avoid reaching Amazon request limits.
 
 ```python
-# Wait 4 seconds between requests
-amazon = AmazonApi(KEY, SECRET, TAG, COUNTRY, throttling=4)
+amazon = AmazonCreatorsApi(ID, SECRET, VERSION, TAG, COUNTRY, throttling=4)  # Makes 1 request every 4 seconds
+amazon = AmazonCreatorsApi(ID, SECRET, VERSION, TAG, COUNTRY, throttling=0)  # No wait time between requests
+```
+
+### Working with Models
 
-# No throttling (use with caution)
-amazon = AmazonApi(KEY, SECRET, TAG, COUNTRY, throttling=0)
+All SDK models are re-exported through `amazon_creatorsapi.models` for convenient access:
+
+```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)
 ```
 
+---
+
 ## Documentation
 
 - 📖 [Full Documentation](https://python-amazon-paapi.readthedocs.io/)
@@ -133,7 +165,7 @@ uv sync
 uv run pre-commit install
 ```
 
-3. Copy `.env.template` to `.env` and add your Amazon API credentials for integration tests.
+3. Copy `.env.template` to `.env` and add your API credentials for integration tests.
 
 Pre-commit hooks will automatically run Ruff, mypy, and tests before each commit.
 

amazon_creatorsapi/__init__.py

@@ -0,0 +1,11 @@
+"""Amazon Creators API wrapper for Python.
+
+A Python wrapper for the Amazon Creators API.
+"""
+
+__author__ = "Sergio Abad"
+__all__ = ["AmazonCreatorsApi", "Country", "models"]
+
+from . import models
+from .api import AmazonCreatorsApi
+from .core import Country