Marketplace API

通过同一组操作和同一个响应结构访问 Amazon、Shopify、Walmart、TikTok Shop 和 AliExpress。

Marketplace API 通过相同的操作和同一个响应结构提供四个电商平台的数据。来自 Amazon 的商品和来自 Shopify 的商品都以相同的 Product 返回，因此读取一个平台的代码也能读取所有平台。电商平台是路径中的一段：

curl "https://gateway.apinoa.com/v1/amazon/search?query=wool+socks" -H "x-api-key: $APINOA_API_KEY"
curl "https://gateway.apinoa.com/v1/walmart/search?query=wool+socks" -H "x-api-key: $APINOA_API_KEY"

操作

操作	返回	作用
`search`	`SearchResult`	匹配关键词的商品，支持过滤
`image-search`	`SearchResult`	匹配图片的商品
`browse`	`SearchResult`	某个类目中的商品，无需关键词
`categories`	`CategoryList`	类目树的一层，用于查找 `browse` 接受的 id
`catalog`	`SearchResult`	某个店铺的全部商品
`product`	`Product`	一个商品的完整信息：变体、图片、规格、卖家、配送
`reviews`	`ReviewPage`	商品的评论，每次一页
`shipping`	`ShippingQuote`	将一件商品配送到某个国家的费用，按承运商列出

每个类型都在 Response Schema 中逐字段说明。

各电商平台支持的操作

	search	image-search	browse	categories	catalog	product	reviews	shipping
Amazon	✓	✓	✓	✓		✓
Shopify	✓	✓			✓	✓	✓
Walmart	✓		✓	✓		✓	✓
TikTok Shop	✓		✓	✓	✓	✓	✓
AliExpress	✓	✓	✓	✓		✓		✓

空白单元格表示该电商平台没有对应该操作的数据来源，而不是计划中。Amazon 评论不可用。Shopify 没有 browse 或 categories，因为它由数百万家独立店铺组成，没有共享的类目树；请改用 catalog 列出单个店铺的商品。

eBay 暂时不可用。在恢复之前，其接口返回 404 UNKNOWN_MARKETPLACE。

相同之处与不同之处

	所有平台一致	因电商平台而异
响应类型	✓ `SearchResult`、`Product`、`ReviewPage`
字段名称与含义	✓ `price` 始终是买家当前支付的价格
过滤器名称与单位	✓ `priceMin` 始终是以主货币单位表示的小数金额
哪些字段有值		只有 Amazon 和 Walmart 返回 `reviewSummary`；只有 AliExpress 以数字形式给出 `stock`
有哪些操作		见上表
接受哪些过滤器		Amazon 的 `brands` 收费 2 个单位；AliExpress 不接受 `ratingMin`
分页		Shopify 按 `cursor` 分页；其他平台按 `page`
商品 id 格式		ASIN、数字 id 或 `shop/handle`

解析代码只需编写一次，但在编写请求之前请先阅读对应电商平台的页面：每个页面都准确列出了它接受的内容，以及每个可选字段实际出现的频率。共享的过滤器词汇见 Filters。

类目与浏览

browse 无需关键词即可列出某个类目；categories 告诉你存在哪些 id。不带 categoryId 调用 categories 获取顶层类目，传入 id 则列出其子类目。不同之处在于 id 的种类：Amazon 的部门是店铺 slug，Walmart 的是数字 id，浏览时以下划线连接成链，AliExpress 的则是普通类目 id。

并非每个类目都列出商品：许多只是导航层级。categories?browsableOnly=true 只返回 browse 接受的 id。无法确定某个类目能否浏览时，browsable 会缺失，而不是 false。没有该数据的电商平台返回 400 BROWSABLE_ONLY_UNAVAILABLE。

运行时查询

GET /v1/marketplaces 发布完整目录：每个平台、其操作、每个操作的费用，以及每个操作输入的 JSON Schema。请基于它生成代码，而不是硬编码这些页面的内容。节选：

{
  "success": true,
  "data": {
    "marketplaces": [
      {
        "id": "walmart",
        "kind": "marketplace",
        "operations": ["search", "browse", "categories", "product", "reviews"],
        "regions": ["US"],
        "cost": { "search": { "base": 1, "max": 1 }, "product": { "base": 1, "max": 1 } },
        "params": {
          "search": {
            "type": "object",
            "required": ["query"],
            "properties": { "query": { "type": "string", "minLength": 1, "description": "Keywords to search for. …" } }
          }
        }
      }
    ],
    "pricing": {
      "currency": "USD",
      "unitPrice": { "marketplace": "0.001000", "image-translate": "0.003000" },
      "dayBoundary": "UTC",
      "dailyBrackets": [{ "fromUnits": 0, "ratePct": 100 }, { "fromUnits": 1000, "ratePct": 90 }]
    }
  }
}

操作名称与 URL 中的写法完全一致（image-search），因此可以直接放入 /v1/{platform}/{operation}。kind 为 marketplace 或 sns。

价格

按标价每单位 $0.001，随当日调用量增长逐级下降（参见 Pricing）。大多数调用为一个单位。以下调用可能花费更多，各有上限：

操作	价格	增加费用的因素
Amazon `search`, `browse`	$0.001，最高 $0.002	`brands` 或 `facets` 使其变为 2 个单位
Amazon `image-search`	$0.001，最高 $0.002	图片有匹配时为 2 个单位；无任何匹配时为 1 个
Amazon `product`	$0.002，最高 $0.032	固定 2 个单位：商品页及其下半部分（规格、畅销排名、评分分布）。`include=offers`：每页十条报价再加一个单位，最多 30 页
Shopify `reviews`	$0.001，最高 $0.007	首页可能产生额外单位；`cursor` 页不会
AliExpress `product`	$0.001，最高 $0.002	`include=shipping` 使其变为 2 个单位
AliExpress `shipping`	$0.001，最高 $0.002	除非 `sku` 是数字 SKU id，否则为 2 个单位

目录以单位给出相同的数字：cost.base 是一次调用的收费，cost.max 是最高收费，一个单位为 pricing.unitPrice。失败的调用不计费。

参考

Response Schema：每个类型的每个字段
Filters：过滤器词汇以及各电商平台接受哪些
Errors：每个错误代码

Marketplace API

操作

各电商平台支持的操作

相同之处与不同之处

类目与浏览

运行时查询

价格

参考

本页内容