Amazon PA-API v5 Actor (JP / US / UK / DE)

Amazon Product Advertising API v5 (PA-API v5) 専用の Apify Actor. SearchItems / GetItems / GetVariations を AWS Signature V4 で署名して呼び出し、 4 リージョン (co.jp / com / co.uk / de) に対応する。

• AWS Signature V4 自前実装 — botocore 不要、軽量ビルド
• httpx + asyncio — 高速・同期 I/O なしの非同期通信
• mypy strict — 0 errors
• 70 件の pytest — AWS 署名 / パース / Apify 統合を全てカバー
• Apify Store 公開対応 — 価格戦略・SEO ドキュメント同梱
• MIT ライセンス

---

特徴

機能	説明
SearchItems	キーワード / カテゴリ / 価格フィルタ / ソート (Relevance / PriceLowToHigh / PriceHighToLow / NewestArrivals)
GetItems	ASIN を最大 10 件直接指定して取得
GetVariations	親 ASIN からバリエーション展開
Multi-region	co.jp / com / co.uk / de を region 入力で切替

---

必要環境

• Python 3.11+
• Amazon アソシエイト・アカウント (Associate Tag)
• AWS IAM ユーザー (ProductAdvertisingAPI:* ポリシー付与済み)
• (デプロイ時のみ) Apify Personal API Token

詳細は docs/paapi-setup.md を参照.

---

インストール

git clone <your-fork-or-clone-url> amazon-paapi-jp-actor
cd amazon-paapi-jp-actor
pip install -r requirements.txt -r requirements-dev.txt

---

ローカル実行

.env を .env.example からコピーして値を埋める:

cp .env.example .env
set -a; source .env; set +a

テスト実行

# 全 70 件のテスト.
python3 -m pytest tests/ -v

# AWS Signature V4 関連.
python3 -m pytest tests/test_paapi_client.py -v

# 型チェック (mypy strict).
mypy src/

smoke test (実 API を 1 回呼ぶ)

$LOCAL_KEYWORD="Nintendo Switch" LOCAL_MAX_ITEMS=5 python3 -m src

ログに「取得件数: N」と表示されれば成功.

---

Apify へのデプロイ

export APIFY_TOKEN=apify_api_xxxxxxxxxxxx
python3 scripts/deploy_apify.py

スクリプトは次の順に処理:

1. Actor を作成 (既存なら再利用)
2. Version 作成 (ソースコードを TAR でアップロード)
3. ビルドを起動
4. ビルド完了までポーリング

詳細は docs/deploy-guide.md を参照.

---

Apify INPUT_SCHEMA

フィールド	型	必須	デフォルト	説明
keyword	string	✓	—	検索キーワード (1〜200 文字)
category	string	—	—	Amazon の SearchIndex (例: Electronics)
maxItems	int	—	10	1〜10 (PA-API v5 上限)
sortBy	enum	—	Relevance	Relevance / PriceLowToHigh / PriceHighToLow / NewestArrivals
minPrice	int	—	—	最低価格
maxPrice	int	—	—	最高価格
region	enum	—	co.jp	co.jp / com / co.uk / de

---

出力フォーマット

各レコードは以下のキーを持つ:

{
  "asin": "B08N5WRWNW",
  "title": "Echo Dot (第4世代) - スマートスピーカー",
  "url": "https://www.amazon.co.jp/dp/B08N5WRWNW",
  "imageUrl": "https://m.media-amazon.com/images/I/echodot.jpg",
  "price": "¥5,980",
  "currency": "JPY",
  "listPrice": "¥7,980",
  "discountPercent": 25,
  "rating": "4.7",
  "reviewCount": "1234",
  "availability": "在庫あり",
  "isPrime": true,
  "category": "CE",
  "scrapedAt": "2026-09-05T15:00:00Z"
}

---

ディレクトリ構成

amazon-paapi-jp-actor/
├── .actor/
│   ├── actor.json         # Apify Actor メタデータ
│   └── INPUT_SCHEMA.json  # 入力フォーム定義
├── src/
│   ├── __init__.py        # パッケージマーカー
│   ├── __main__.py        # `python3 -m src` エントリポイント
│   ├── main.py            # Apify Actor の main()
│   ├── paapi_client.py    # AWS Signature V4 + httpx クライアント
│   ├── parser.py          # PA-API レスポンス → ProductRecord
│   └── models.py          # TypedDict / 定数定義
├── tests/
│   ├── conftest.py
│   ├── test_paapi_client.py   # AWS 署名 + httpx モック (45 tests)
│   ├── test_parser.py         # パーサ (17 tests)
│   └── test_main.py           # Actor 統合 (13 tests)
├── scripts/
│   └── deploy_apify.py    # ワンコマンドデプロイ
├── docs/
│   ├── paapi-setup.md          # PA-API 認証情報セットアップ
│   ├── deploy-guide.md         # Apify デプロイ手順
│   └── seo-keyword-strategy.md # SEO キーワード戦略
├── Dockerfile
├── requirements.txt
├── requirements-dev.txt
├── mypy.ini
├── .env.example
├── .gitignore
├── LICENSE                  # MIT
└── README.md                # このファイル

---

開発メモ

• PA-API v5 は 1 req/sec のレート制限. 連続実行を避け、必要なら sleep_ms 入力で待機を入れる.
• AWS Signature V4 は docs/paapi-setup.md の IAM ポリシーが必要.
• mypy.ini で strict = True を有効化済み. CI で 0 errors を維持すること.
• テストは全て httpx をモック化しており、実 API の呼び出しは行わない (1 テスト 0.1 秒以下).

---

ライセンス

MIT License — 詳細は LICENSE を参照.