1688关键词搜索 API

Q: 价格筛选为什么和详情页的价格对不上？

1688 是阶梯价，采购数量不同单价不同。min_price、max_price 只按搜索页的价格筛选，不保证每个规格、每个数量档都在区间内；最终报价以商品详情里的阶梯价为准。

Q: city 是什么意思？

它是商品查询的城市筛选条件，不是你的账号所在地，也不会改变返回的供应商地址。要看货源地，请读结果里的 city 和 province。

Q: 怎么挑适合一件代发的货源？

先看 supports_dropship 是否为真，再结合 min_order_quantity 和 is_out_of_stock 判断能否小批量拿货、当前有没有货；repurchase_rate 高、supplier_years 长的供应商通常更稳定。

POST

接口健康状态

24h 健康值: 正常
24h 平均耗时: —

健康 / 正常
可用
少量可用
基本不可用

正常

24 小时趋势

30 天趋势

关键词搜索：返回列表，默认 20 条、单次最多 100 条；主要字段 id、url、title、text、price_min、price_max。

1688 关键词搜索按 keyword 检索批发商品，返回标题、价格区间、最小起订量、订单数、复购率、供应商名称与所在地、经营模式和入驻年限、是否缺货和是否支持一件代发。它回答「这个品类在 1688 上有哪些货源、起订和价格大概怎样」，是找供应商、比货源和无货源选品的第一步。

用 min_price、max_price 圈价格，用 city 按城市筛选，用 sort 按相关度、畅销或价格升降排序。采购前先看 min_order_quantity；repurchase_rate 和 supplier_composite_score 可以在打开详情前先筛一遍供应商。价格筛选不保证每个规格和数量档都在区间内，阶梯价以商品详情为准。

单价 $1.39 / 千次（每次 $0.001389），失败与空结果不扣费。同步返回；慢任务可在请求体加 "mode": "async"，先拿 job_id 再轮询。

AI 提示词

复制下面这段给你常用的 AI 助手：里面写好了这个接口的参数、返回字段和示例请求，它会先问清你的需求，再帮你写采集脚本。

请帮我用 EveryInfra 的「1688 关键词搜索」接口（alibaba1688/search）写一个数据采集脚本。

接口约定：
- 请求：POST https://api.everyinfra.com/api/v1/social，请求头 Authorization: Bearer <API Key>；Key 从环境变量 EVERYINFRA_API_KEY 读取，不要写进代码。
- 请求体里 platform 填 alibaba1688，action 填 search，参数放在 params 里。
- 必填参数：
  - keyword：1688 批发商品搜索词，例如保温杯、包装纸盒。用于 search，不是店铺名或 offerId；起订量和阶梯价属于返回的商品信息。
- 可选参数：
  - city：1688 商品查询的城市筛选文本。它不是账号所在地，也不会修改返回供应商的地址；指定单品时不能据此推断该筛选仍生效。
  - max_price：批发商品价格筛选上限，数值；不是阶梯报价中的采购数量上限。与 min_price 配合限定价格范围，不能保证每个 SKU 或数量档都处于该范围。
  - min_price：批发商品价格筛选下限，数值；不是最低起订量或 API 调用预算。不同采购数量可能对应不同阶梯价，不能把筛选价当作最终成交报价。
  - sort：商品搜索排序：relevance 为相关度，popular 为畅销优先，price_asc / price_desc 为价格升序 / 降序。不传时 search 使用 relevance；排序不等于返回精确销量或成交额。（可选值：popular / price_asc / price_desc / relevance）
  - limit：这次调用最多返回的条数，整数，1–100；不传按默认值，实际返回可能少于这个数。超过上限会在扣费前返回 422。（默认 20）
- 返回一组记录，每条记录的主要字段：id、url、title、text、price_min（价格区间下限）、price_max（价格区间上限）、currency、min_order_quantity（最小起订量(MOQ)）、order_count（订单数）、repurchase_rate（复购率）、category、city；一共 24 个字段，完整列表见 https://api.everyinfra.com/api/v1/social/catalog?platform=alibaba1688。
- 示例请求体：
{
  "platform": "alibaba1688",
  "action": "search",
  "params": {
    "keyword": "不锈钢保温杯"
  }
}
- 计费：$1.39 / 千次；失败和空结果不扣费。
- 一次要采几十上百个时，在请求体加 "mode": "async"：先拿到 job_id，再轮询 GET https://api.everyinfra.com/api/v1/jobs/{job_id} 取结果。
- 返回 422 时，按错误信息里的候选参数和允许值修正；返回 429 或 503 时，按 Retry-After 等待后重试。

写代码前，先问清楚我要采哪些对象、一共多少个、需要哪些字段、结果存成什么格式，再把方案和大概花费讲给我确认。

请求参数

参数名	位置	类型	必填	默认值	说明
`Authorization`	header	`string`	是	-	Bearer 加你的 API Key。在控制台创建；不要放进网址或代码仓库。
`platform`	body	`string`	是	`alibaba1688`	平台标识，固定值。
`action`	body	`string`	是	`search`	能力标识，固定值。
`keyword`	body.params	未声明	是	-	1688 批发商品搜索词，例如保温杯、包装纸盒。用于 search，不是店铺名或 offerId；起订量和阶梯价属于返回的商品信息。
`city`	body.params	未声明	否	-	1688 商品查询的城市筛选文本。它不是账号所在地，也不会修改返回供应商的地址；指定单品时不能据此推断该筛选仍生效。
`max_price`	body.params	未声明	否	-	批发商品价格筛选上限，数值；不是阶梯报价中的采购数量上限。与 min_price 配合限定价格范围，不能保证每个 SKU 或数量档都处于该范围。
`min_price`	body.params	未声明	否	-	批发商品价格筛选下限，数值；不是最低起订量或 API 调用预算。不同采购数量可能对应不同阶梯价，不能把筛选价当作最终成交报价。
`sort`	body.params	`enum`	否	-	商品搜索排序：relevance 为相关度，popular 为畅销优先，price_asc / price_desc 为价格升序 / 降序。不传时 search 使用 relevance；排序不等于返回精确销量或成交额。允许值`popularprice_ascprice_descrelevance`
`limit`	body.params	`integer (1–100)`	否	`20`	这次调用最多返回的条数，整数，1–100；不传按默认值，实际返回可能少于这个数。超过上限会在扣费前返回 422。

代码示例

bash

curl -X POST 'https://api.everyinfra.com/api/v1/social' \
  -H "Authorization: Bearer $EVERYINFRA_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "platform": "alibaba1688",
  "action": "search",
  "params": {
    "keyword": "不锈钢保温杯"
  }
}'

[OpenAPI 定义 (JSON)]示例从环境变量 EVERYINFRA_API_KEY 读取 Key，复制出去的代码不含你的 Key。

按批发商品名称检索；不是供应商主页查询。

响应示例

真实返回样例

2026年10月13日 12:57（北京时间）用上方代码示例的参数真实调用所得。results 与 count 是那次的真实返回，已隐去名字、账号、头像、主页链接、联系方式等个人信息，列表只保留前 2 条；id、billing、quota 每次调用都不同，只给结构。

json

{
  "id": "req_…",
  "platform": "alibaba1688",
  "action": "search",
  "results": [
    {
      "id": "（已隐去）",
      "url": "https://detail.1688.com/offer/901095512547.html",
      "title": "跨境美式太空壶304不锈钢双层真空保温杯大容量运动水壶登山水壶",
      "price_min": 12.5,
      "currency": "CNY",
      "order_count": 33,
      "repurchase_rate": 20,
      "city": "永康市",
      "province": "浙江",
      "supplier_name": "永康市钛霖杯业有限公司",
      "images": [
        "https://cbu01.alicdn.com/img/ibank/O1CN01LbpPbm2B0StIPXCWn_!!2219521848276-0-cib.jpg"
      ],
      "supplier_type": "生产加工",
      "supplier_years": 2,
      "supplier_shop_url": "https://shop81l5635to8463.1688.com",
      "sold_count_text": "已售1200+件",
      "service_tags": [
        "退货包运费",
        "先采后付",
        "回头率54%"
      ],
      "product_badges": [
        "先采后付"
      ],
      "platform": "1688"
    },
    {
      "id": "（已隐去）",
      "url": "https://detail.1688.com/offer/1080785307425.html",
      "title": "新款彩色304不锈钢保温杯 便携手提弹跳盖户外便携运动水杯定 制",
      "price_min": 24,
      "currency": "CNY",
      "min_order_quantity": 1,
      "order_count": 49,
      "repurchase_rate": 14,
      "city": "金华市",
      "province": "浙江",
      "supplier_name": "永康市大表哥工贸有限公司",
      "images": [
        "https://cbu01.alicdn.com/img/ibank/O1CN01NbBs3QLcV7L3thOC_!!2217763939489-0-cib.jpg"
      ],
      "supplier_type": "生产加工",
      "supplier_years": 3,
      "supplier_shop_url": "https://15727971454.1688.com",
      "sold_count_text": "已售500+件",
      "service_tags": [
        "退货包运费",
        "先采后付",
        "回头率67%"
      ],
      "product_badges": [
        "7×24H响应",
        "先采后付"
      ],
      "platform": "1688"
    }
  ],
  "count": 20,
  "billing": {
    "charged": …,
    "charged_usd": …,
    "balance_after_usd": …,
    …
  },
  "quota": { … }
}

返回字段

业务数据在 results 里；下表是每条记录可能包含的字段，平台没有提供的值不会被补造。

字段	含义
`id`	该记录在原平台上的唯一标识。仅在同一平台内唯一，跨平台可能重复。
`url`	该记录在原平台上的可访问链接。
`title`	标题。平台无标题概念时（如纯文本帖）为 null。
`text`	正文内容，已去除 HTML 标签，全文返回、不截断（个别平台的列表结果本身只有摘要，以该平台的字段说明为准）。
`price_min`	价格区间下限。
`price_max`	价格区间上限。
`currency`	价格币种代码（如 CNY、USD）。price 存在但 currency 为 null 时不要假定币种。
`min_order_quantity`	最小起订量(MOQ)。1688 批发场景的第一门槛，采购前先看它。
`order_count`	订单数。
`repurchase_rate`	复购率。1688 上判断供应商质量最硬的指标之一。
`category`	分类名称，取值为原平台的分类体系，未做跨平台归一。
`city`	城市名，用原平台的语言书写，未做中英归一。
`province`	供应商所在省份。
`supplier_name`	供应商名称。
`is_out_of_stock`	是否缺货。
`supports_dropship`	是否支持一件代发。做无货源电商的关键筛选项。
`images`	商品图片。
`supplier_type`	供应商经营模式（如生产加工、经销批发）。
`supplier_years`	供应商在 1688 平台的年数。
`supplier_shop_url`	供应商店铺链接。
`supplier_composite_score`	供应商综合服务分（1-5）。
`sold_count_text`	销量的原文展示（搜索行，如全网100+件）。
`service_tags`	服务标签列表（搜索行）。
`product_badges`	商品徽章列表（搜索行，如 7×24H响应、先采后付）。
`platform`	数据来源平台标识，与请求里的 platform 一致（如 xiaohongshu、tiktok）。

常见问题

价格筛选为什么和详情页的价格对不上？

1688 是阶梯价，采购数量不同单价不同。min_price、max_price 只按搜索页的价格筛选，不保证每个规格、每个数量档都在区间内；最终报价以商品详情里的阶梯价为准。

`city` 是什么意思？

它是商品查询的城市筛选条件，不是你的账号所在地，也不会改变返回的供应商地址。要看货源地，请读结果里的 city 和 province。

怎么挑适合一件代发的货源？

先看 supports_dropship 是否为真，再结合 min_order_quantity 和 is_out_of_stock 判断能否小批量拿货、当前有没有货；repurchase_rate 高、supplier_years 长的供应商通常更稳定。

错误与计费

401: 缺少 Key 或 Key 无效。先鉴权再校验参数，未鉴权的请求拿不到参数结构。
422: 参数名或取值不对。错误信息会列出这项能力支持的参数、允许值和最接近的候选，按它改即可；发生在扣费之前。
402: 余额不足，请先充值。
429: 超过账户的每分钟请求上限（名下所有 Key 合计；Key 自设了更低上限时先按它算），按 Retry-After 等待后再试。需要更高上限可在控制台买提速包。
503: 暂时无法完成。已预扣的费用按原账本退回；响应里的 billing 与 refund 写明实际结果，结果未知时会明确标出，不要直接重发。
200 空结果: 请求完成但没有数据，不扣费（billing.reason = empty_result_refunded）。