{"id":36687576,"url":"https://github.com/goark/pa-api","last_synced_at":"2026-05-12T02:05:38.716Z","repository":{"id":43191259,"uuid":"210358025","full_name":"goark/pa-api","owner":"goark","description":"APIs for Amazon Product Advertising API v5 by Golang","archived":false,"fork":false,"pushed_at":"2026-01-10T05:01:24.000Z","size":145,"stargazers_count":39,"open_issues_count":0,"forks_count":14,"subscribers_count":3,"default_branch":"master","last_synced_at":"2026-01-11T01:32:02.993Z","etag":null,"topics":["api-wrapper","golang","golang-package","product-advertising-api"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/goark.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2019-09-23T13:09:12.000Z","updated_at":"2026-01-10T04:56:45.000Z","dependencies_parsed_at":"2025-09-11T00:23:35.997Z","dependency_job_id":"1a91e3e5-28d4-49e3-b891-c640d7c2fd62","html_url":"https://github.com/goark/pa-api","commit_stats":null,"previous_names":["spiegel-im-spiegel/pa-api"],"tags_count":34,"template":false,"template_full_name":null,"purl":"pkg:github/goark/pa-api","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/goark%2Fpa-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/goark%2Fpa-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/goark%2Fpa-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/goark%2Fpa-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/goark","download_url":"https://codeload.github.com/goark/pa-api/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/goark%2Fpa-api/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28338970,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-12T10:58:46.209Z","status":"ssl_error","status_checked_at":"2026-01-12T10:58:42.742Z","response_time":98,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api-wrapper","golang","golang-package","product-advertising-api"],"created_at":"2026-01-12T11:16:07.866Z","updated_at":"2026-05-12T02:05:38.702Z","avatar_url":"https://github.com/goark.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# [pa-api] -- Go client for the Amazon Creators API\n\n[![ci](https://github.com/goark/pa-api/actions/workflows/ci.yml/badge.svg)](https://github.com/goark/pa-api/actions/workflows/ci.yml)\n[![CodeQL](https://github.com/goark/pa-api/actions/workflows/codeql.yml/badge.svg)](https://github.com/goark/pa-api/actions/workflows/codeql.yml)\n[![Go Reference](https://pkg.go.dev/badge/github.com/goark/pa-api.svg)](https://pkg.go.dev/github.com/goark/pa-api)\n[![GitHub license](https://img.shields.io/badge/license-Apache%202-blue.svg)](https://raw.githubusercontent.com/goark/pa-api/master/LICENSE)\n[![GitHub release](https://img.shields.io/github/release/goark/pa-api.svg)](https://github.com/goark/pa-api/releases/latest)\n\nA Go client for [Amazon's Creators API][creatorsapi-docs], the OAuth2-based replacement for the now-retired Product Advertising API v5 (PA-API). The package keeps the import path `github.com/goark/pa-api` and the package name `paapi5` so existing call sites need only minor changes; under the hood the wire protocol, authentication and host all change.\n\nThis package requires Go 1.25.10 or later.\n\n### Go version policy\n\n- The source of truth for the minimum supported Go version is `go.mod`.\n- README and CI are kept aligned with `go.mod`.\n- If the `go` directive changes, update this README line in the same change.\n\n## Migrating from PA-API v5\n\nAmazon retired PA-API v5 on 2026-05-15 and replaced it with the Creators API. The two big differences:\n\n| | PA-API v5 (old) | Creators API (new) |\n|---|---|---|\n| Host | `webservices.amazon.\u003ctld\u003e` per locale | Single `creatorsapi.amazon` for every marketplace |\n| Marketplace selection | `Marketplace` body field | `x-marketplace` request header |\n| Auth | AWS SigV4 (Access Key + Secret Key) | OAuth2 client_credentials (Credential ID + Credential Secret + Version) |\n| Body keys | `PascalCase` | `lowerCamelCase` |\n| Resource enums | `Images.Primary.Medium` | `images.primary.medium` |\n| `Offers` (V1) | Available | Removed; use `OffersV2` |\n\nCode-level changes you should expect when upgrading:\n\n- **`CreateClient` / `DefaultClient` arguments**: the second/third positional arguments are now `credentialID` and `credentialSecret` (Creators API credentials issued via Associates Central) instead of AWS access/secret keys.\n- **`q.EnableOffers()`** is now an alias for `q.EnableOffersV2()` with a deprecation comment; the V1 Offers resource is gone.\n- **`Server.Region()` is deprecated** and is no longer used by the client; it remains for back-compat callers that record it as metadata.\n- **Response JSON keys** returned by the Creators API are lowerCamelCase. The existing Go field names in `entity.Response` decode case-insensitively from these new keys, but if your code re-serialises a `Response` value you'll see PascalCase output for some fields and lowerCamelCase for the explicitly tagged ones (notably `id`).\n- **`SearchItems` filters** `Marketplace`, `PartnerType`, `Merchant`, and `OfferCount` are silently ignored — those fields are not accepted by the Creators API. Existing code using those filters compiles but the values are dropped.\n- **Query constructor `marketplace` arguments are compatibility-only** (`NewGetItems`, `NewSearchItems`, `NewGetVariations`, `NewGetBrowseNodes`). Actual routing always uses the client's configured marketplace via the `x-marketplace` header, so set marketplace on `Server`/`Client` (`creatorsapi.WithMarketplace(...)`) rather than per-query.\n\n### Ignored legacy request fields\n\nThe library keeps several legacy knobs for source compatibility, but the Creators API does not accept them in request bodies. They are currently treated as no-ops.\n\n| Legacy field / option | Previous behavior (PA-API v5) | Current behavior (Creators API) |\n|---|---|---|\n| `Marketplace` request body field | Selected target marketplace in-body | Ignored in-body. Routing is done by `x-marketplace` header |\n| `PartnerType` (`Associates`) | Explicit body parameter | Ignored. Partner type is implicit |\n| `Merchant` | Offer filtering selector | Ignored |\n| `OfferCount` | Offer summary limiter | Ignored |\n\n### Marketplace routing precedence\n\nMarketplace selection is evaluated in this order:\n\n1. `Server`/`Client` marketplace (for example `creatorsapi.WithMarketplace(...)`)\n2. Request header `x-marketplace` sent by the client\n\nQuery constructor marketplace arguments are retained only for compatibility and are not used to route requests.\n\n### Credential Version map\n\nCreators API credentials are region-group scoped. Use credentials that match the marketplace group you call.\n\nNew applications typically receive **v3.x** credentials (Login with Amazon token endpoints). **v2.x** credentials use regional Cognito endpoints and a different OAuth scope and catalog `Authorization` header shape; if Associates Central still shows `2.1`/`2.2`/`2.3`, pass `creatorsapi.WithCredentialVersion(\"2.1\")` (etc.) on `CreateClient`.\n\n| Credential Version | Region group | Token endpoint (default) | Catalog `Authorization` |\n|---|---|---|---|\n| `3.1` | North America | `https://api.amazon.com/auth/o2/token` | `Bearer \u003ctoken\u003e` |\n| `3.2` | Europe / Middle East / India | `https://api.amazon.co.uk/auth/o2/token` | `Bearer \u003ctoken\u003e` |\n| `3.3` | Far East | `https://api.amazon.co.jp/auth/o2/token` | `Bearer \u003ctoken\u003e` |\n| `2.1` | North America | `https://creatorsapi.auth.us-east-1.amazoncognito.com/oauth2/token` | `Bearer \u003ctoken\u003e, Version 2.1` |\n| `2.2` | Europe / Middle East / India | `https://creatorsapi.auth.eu-south-2.amazoncognito.com/oauth2/token` | `Bearer \u003ctoken\u003e, Version 2.2` |\n| `2.3` | Far East | `https://creatorsapi.auth.us-west-2.amazoncognito.com/oauth2/token` | `Bearer \u003ctoken\u003e, Version 2.3` |\n\nExample marketplace groups (same as before): NA — `www.amazon.com`, `www.amazon.ca`, `www.amazon.com.mx`, `www.amazon.com.br`; EU — `www.amazon.co.uk`, `www.amazon.de`, `www.amazon.fr`, `www.amazon.in`, `www.amazon.sa`, `www.amazon.ae`; FE — `www.amazon.co.jp`, `www.amazon.sg`, `www.amazon.com.au`.\n\nIf token acquisition fails with an auth error, verify that your credential version and marketplace group match.\n\n### Rate limits and retry guidance\n\nAmazon starts new credential sets with low throughput (commonly around 1 TPS; check your Associates Central quota for authoritative limits). Build callers with backpressure and retry control.\n\nRecommended client behavior:\n\n- Treat `429` and transient `5xx` as retryable.\n- Use exponential backoff with jitter.\n- Cap retry attempts and total request timeout.\n- Avoid synchronized retries across workers.\n- Consider per-credential rate limiting in your application.\n\n### Getting Creators API credentials\n\nOnly the primary Amazon Associates account owner can mint credentials. From [Associates Central][creatorsapi-portal] go to **Tools** → **Creators API** → **Create Application**, then **Add New Credential**. Copy the Credential Secret immediately — it is only shown once. Note the **Credential Version** shown for your credential (`3.1`/`3.2`/`3.3` for Login with Amazon, or legacy `2.1`/`2.2`/`2.3` for Cognito). You'll need it if you call multiple regions from the same process or if your credential region group does not match the configured marketplace.\n\n### Quick migration checklist\n\nUse this path when migrating existing PA-API v5 call sites:\n\n1. Keep the import path as `github.com/goark/pa-api` (alias as `creatorsapi` in examples if preferred).\n2. Replace client credential inputs: AWS Access Key / Secret Key -\u003e Creators API Credential ID / Credential Secret.\n3. Configure marketplace on `Server`/`Client` (`WithMarketplace`) and do not rely on per-query marketplace arguments.\n4. Replace V1 offers usage with OffersV2 (`EnableOffersV2`; `EnableOffers` remains as a compatibility alias).\n5. Remove expectations around `Merchant`, `OfferCount`, and `PartnerType` request effects; these are ignored.\n6. Confirm Credential Version matches the marketplace group you call (`3.1`/`3.2`/`3.3` by default per marketplace, or `2.1`/`2.2`/`2.3` for legacy Cognito credentials via `WithCredentialVersion`).\n7. Add retry and rate-limit control for `429` and transient `5xx` responses.\n8. Run local verification with your project's standard test/lint workflow before opening a PR.\n\n## Usage\n\n### Create a server configuration\n\n```go\nsv := creatorsapi.New() // default: US marketplace, NA credential version 3.1 (Login with Amazon)\nfmt.Println(\"Marketplace:\", sv.Marketplace())\nfmt.Println(\"CredentialVersion:\", sv.CredentialVersion())\nfmt.Println(\"URL:\", sv.URL(creatorsapi.GetItems.Path()))\n// Output:\n// Marketplace: www.amazon.com\n// CredentialVersion: 3.1\n// URL: https://creatorsapi.amazon/catalog/v1/getItems\n```\n\nFor another marketplace:\n\n```go\nsv := creatorsapi.New(creatorsapi.WithMarketplace(creatorsapi.LocaleJapan)) // Japan -\u003e credential version 3.3\nfmt.Println(\"Marketplace:\", sv.Marketplace())\nfmt.Println(\"CredentialVersion:\", sv.CredentialVersion())\n// Output:\n// Marketplace: www.amazon.co.jp\n// CredentialVersion: 3.3\n```\n\nThe credential version is auto-derived from the configured marketplace's region group (`3.1`/`3.2`/`3.3`). Override with `creatorsapi.WithCredentialVersion(\"2.2\")` when using legacy Cognito credentials (`2.1`/`2.2`/`2.3`), or when your credential group differs from the marketplace default.\n\n### Create a client\n\n```go\nclient := creatorsapi.DefaultClient(\"mytag-20\", \"YOUR_CREDENTIAL_ID\", \"YOUR_CREDENTIAL_SECRET\")\nfmt.Println(\"Marketplace:\", client.Marketplace())\n// Output:\n// Marketplace: www.amazon.com\n```\n\nFor a different marketplace plus a custom `*http.Client`:\n\n```go\nclient := creatorsapi.New(\n    creatorsapi.WithMarketplace(creatorsapi.LocaleJapan),\n).CreateClient(\n    \"mytag-20\",\n    \"YOUR_CREDENTIAL_ID\",\n    \"YOUR_CREDENTIAL_SECRET\",\n    creatorsapi.WithHttpClient(http.DefaultClient),\n)\n```\n\nThe client transparently obtains and caches an OAuth2 access token from the appropriate Cognito endpoint (`expires_in` minus a 30-second leeway) and forwards it to the API as `Authorization: Bearer \u003ctoken\u003e, Version \u003c2.x\u003e`.\n\n## Sample code\n\n### GetItems\n\n```go\npackage main\n\nimport (\n    \"context\"\n    \"fmt\"\n\n    creatorsapi \"github.com/goark/pa-api\"\n    \"github.com/goark/pa-api/entity\"\n    \"github.com/goark/pa-api/query\"\n)\n\nfunc main() {\n    client := creatorsapi.New(\n        creatorsapi.WithMarketplace(creatorsapi.LocaleJapan),\n    ).CreateClient(\n        \"mytag-20\",\n        \"YOUR_CREDENTIAL_ID\",\n        \"YOUR_CREDENTIAL_SECRET\",\n    )\n\n    q := query.NewGetItems(\n        client.Marketplace(),\n        client.PartnerTag(),\n        client.PartnerType(),\n    ).ASINs([]string{\"B07YCM5K55\"}).EnableImages().EnableItemInfo().EnableParentASIN()\n\n    body, err := client.RequestContext(context.Background(), q)\n    if err != nil {\n        fmt.Printf(\"%+v\\n\", err)\n        return\n    }\n\n    res, err := entity.DecodeResponse(body)\n    if err != nil {\n        fmt.Printf(\"%+v\\n\", err)\n        return\n    }\n    fmt.Println(res.String())\n}\n```\n\n### GetVariations\n\n```go\nq := query.NewGetVariations(\n    client.Marketplace(),\n    client.PartnerTag(),\n    client.PartnerType(),\n).ASIN(\"B07YCM5K55\").EnableImages().EnableItemInfo().EnableParentASIN()\n\nbody, err := client.RequestContext(context.Background(), q)\n```\n\n### SearchItems\n\n```go\nq := query.NewSearchItems(\n    client.Marketplace(),\n    client.PartnerTag(),\n    client.PartnerType(),\n).Search(query.Keywords, \"数学ガール\").EnableImages().EnableItemInfo().EnableParentASIN()\n\nbody, err := client.RequestContext(context.Background(), q)\n```\n\n### GetBrowseNodes\n\n```go\nq := query.NewGetBrowseNodes(\n    client.Marketplace(),\n    client.PartnerTag(),\n    client.PartnerType(),\n).BrowseNodeIds([]string{\"3040\", \"3045\"}).EnableBrowseNodes()\n\nbody, err := client.RequestContext(context.Background(), q)\n```\n\n## Contributors\n\nMany thanks for [contributors](https://github.com/goark/pa-api/graphs/contributors \"Contributors to goark/pa-api\")\n\n## Links\n\n- [Amazon Creators API documentation][creatorsapi-docs]\n- [Associates Central — Creators API portal][creatorsapi-portal]\n\n[pa-api]: https://github.com/goark/pa-api \"goark/pa-api: Go client for the Amazon Creators API\"\n[creatorsapi-docs]: https://affiliate-program.amazon.com/creatorsapi/docs/en-us/introduction\n[creatorsapi-portal]: https://affiliate-program.amazon.com/creatorsapi\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgoark%2Fpa-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgoark%2Fpa-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgoark%2Fpa-api/lists"}