---
title: "Marketplace API"
description: "通过同一组操作和同一个响应结构访问 Amazon、Shopify、Walmart、TikTok Shop 和 AliExpress。"
---

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

```bash
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](/docs/api-reference/marketplaces/response-schema) 中逐字段说明。

## 各电商平台支持的操作

| | search | image-search | browse | categories | catalog | product | reviews | shipping |
|---|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|
| [Amazon](/docs/api-reference/amazon) | ✓ | ✓ | ✓ | ✓ | | ✓ | | |
| [Shopify](/docs/api-reference/shopify) | ✓ | ✓ | | | ✓ | ✓ | ✓ | |
| [Walmart](/docs/api-reference/walmart) | ✓ | | ✓ | ✓ | | ✓ | ✓ | |
| [TikTok Shop](/docs/api-reference/tiktokshop) | ✓ | | ✓ | ✓ | ✓ | ✓ | ✓ | |
| [AliExpress](/docs/api-reference/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](/docs/api-reference/marketplaces/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**。
请基于它生成代码，而不是硬编码这些页面的内容。节选：

```json
{
  "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](/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](/docs/api-reference/marketplaces/response-schema)：每个类型的每个字段
- [Filters](/docs/api-reference/marketplaces/filters)：过滤器词汇以及各电商平台接受哪些
- [Errors](/docs/errors)：每个错误代码