# 1688 关键词搜索 API (alibaba1688.search)

- Canonical page: https://everyinfra.com/alibaba1688-api/search
- Endpoint: POST https://api.everyinfra.com/api/v1/social with {"platform": "alibaba1688", "action": "search", "params": {...}}
- Price: $0.002778 per call ($2.78 per 1,000 requests); failed calls and empty results are not charged
- Returns: list, default 20, max 100 per call
- Mode: sync; add "mode": "async" for slow tasks

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

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

## Health

- Live health (24h percent, hourly and daily trends): https://api.everyinfra.com/api/v1/social/availability?platform=alibaba1688&action=search

## Parameters

| name | type | required | default | description |
|---|---|---|---|---|
| keyword | not declared | yes | not declared | 1688 批发商品搜索词，例如保温杯、包装纸盒。用于 search，不是店铺名或 offerId；起订量和阶梯价属于返回的商品信息。 |
| city | not declared | no | not declared | 1688 商品查询的城市筛选文本。它不是账号所在地，也不会修改返回供应商的地址；指定单品时不能据此推断该筛选仍生效。 |
| max_price | not declared | no | not declared | 批发商品价格筛选上限，数值；不是阶梯报价中的采购数量上限。可带小数；个别情况按整元筛选时向上取整（145.98 按 146），只放宽不收窄。与 min_price 配合限定价格范围，不能保证每个 SKU 或数量档都处于该范围。 |
| min_price | not declared | no | not declared | 批发商品价格筛选下限，数值；不是最低起订量或 API 调用预算。可带小数；个别情况按整元筛选时向下取整（39.81 按 39），只放宽不收窄。不同采购数量可能对应不同阶梯价，不能把筛选价当作最终成交报价。 |
| sort | enum: popular / price_asc / price_desc / relevance | no | not declared | 商品搜索排序：relevance 为相关度，popular 为畅销优先，price_asc / price_desc 为价格升序 / 降序。不传时 search 使用 relevance；排序不等于返回精确销量或成交额。 |
| limit | integer (1–100) | no | 20 | 这次调用最多返回的条数，整数，1–100；不传按默认值，实际返回可能少于这个数。超过上限会在扣费前返回 422。 |

## Response fields (items in `results`)

| field | meaning |
|---|---|
| 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 | 商品主图链接，按页面顺序；product_detail 里有的商品还带规格图，详情区的图在 description_images。没有图片时不出现这个字段。 |
| supplier_type | 供应商经营模式（如 生产加工、经销批发）。商品详情同步调用时可能为空；异步调用通常有值。 |
| supplier_years | 供应商在 1688 平台的年数。商品详情同步调用时可能为空；异步调用通常有值。 |
| supplier_shop_url | 供应商店铺链接。 |
| supplier_composite_score | 供应商综合服务分（1-5）。 |
| sold_count_text | 销量的原文展示（搜索行，如 全网100+件）。 |
| service_tags | 服务标签列表（搜索行）。 |
| product_badges | 商品徽章列表（搜索行，如 7×24H响应、先采后付）。 |
| rating | 商品综合评分（1-5）。商品详情同步调用时可能为空；异步调用通常有值。 |
| rating_scale | 上一列 `rating` 的满分。5 表示五星制、10 表示十分制。只在该行有 rating 时出现。商品详情同步调用时可能为空；异步调用通常有值。 |
| review_count | 累计评价数。商品详情同步调用时可能为空；异步调用通常有值。 |
| positive_rate | 好评率（0-1 小数，如 0.999 = 99.9%）。商品详情同步调用时可能为空；异步调用通常有值。 |
| sold_count | 销量（数字）；只有约数（如 10万+）时缺省，原文见 sold_display。 |
| sold_display | 销量的原文展示（如 已售10万+件）；数字形式见 sold_count。商品详情同步调用时可能为空；异步调用通常有值。 |
| want_buy_count | 想要/求购人数（采购意向热度参考）。商品详情同步调用时可能为空；异步调用通常有值。 |
| stock | 库存。商品详情同步调用时可能为空；异步调用通常有值。 |
| unit | 计价单位（个/件/箱）。 |
| category_path | 完整类目路径（如 数码、电脑 > 手机配件 > 手机保护套）；product_detail 常缺省，类目名见 category。商品详情同步调用时可能为空；异步调用通常有值。 |
| video_url | 商品视频链接（如有）。 |
| winport_url | 供应商 1688 诚信通店铺链接。 |
| supplier_fans | 供应商粉丝数。商品详情同步调用时可能为空；异步调用通常有值。 |
| supplier_founded_year | 供应商成立年份。 |
| price_tiers | 阶梯价（买得越多单价越低）：[{min_quantity, max_quantity, price}]，max_quantity 是该档上限（最后一档没有）。不分数量档的商品没有这个字段，价格看 price_min / price_max。 |
| specs | 商品参数/规格表：[{name, value}] 键值对列表（如 材质: TPU）。商品详情同步调用时可能为空；异步调用通常有值。 |
| description_images | 详情描述图 URL 列表（按商品页原顺序）；null 表示该商品无详情图。商品详情同步调用时可能为空；异步调用通常有值。 |
| coupons | 店铺券与权益列表：每项含 type（类型代码）、type_name（类型名）、label（标签，如 满50包邮）、summary（说明）、valid_from / valid_to（有效期，原文时间）、link_url（活动页）、id；字段缺失时没有该子键。 |
| promotion_details | 促销活动明细：activity_id、name、type（如 sellerProm 店铺活动 / officialProm 平台活动）、detail / summary（规则说明）、valid_period（有效期原文）、discount_amount（优惠金额，元）、original_price_range（活动前价格区间原文）、note（补充说明，如不免邮区域）、link_url。promotions 仍只给名称。 |
| service_details | 服务保障明细：code（服务代码）、name、description（规则说明）、rule_url（规则页）。services / service_tags 只给名称。商品详情同步调用时可能为空；异步调用通常有值。 |
| purchase_limits | 限购：per_buyer（每个买家限购件数）、promotion_per_buyer（活动价限购件数）；-1 表示不限购。 |
| mix_wholesale | 混批条件：min_amount（混批起批金额，元）、min_varieties（最少款数）。 |
| supports_mix | 是否支持混批（不同款式凑单起批）。商品详情同步调用时可能为空；异步调用通常有值。 |
| review_tags | 买家印象标签：[{tag, count}]，如 面料软糯 ×2。商品详情同步调用时可能为空；异步调用通常有值。 |
| refund_rate | 退款率（0-1 小数）。 |
| review_negative_count | 差评数；null 表示没给，不等于 0。 |
| review_neutral_count | 中评数；null 表示没给，不等于 0。 |
| review_with_photo_count | 带图评价数；null 表示没给，不等于 0。商品详情同步调用时可能为空；异步调用通常有值。 |
| review_with_text_count | 有文字的评价数；null 表示没给，不等于 0。商品详情同步调用时可能为空；异步调用通常有值。 |
| supplier_stats | 供应商画像（只含有值的子键）：employee_count（员工数）、plant_area_sqm（厂房面积，平方米）、plant_type（厂房类型，如 自有工厂）、equipment_count（主要设备数）、product_count（在售商品数）、repeat_rate（回头率 0-1）、repeat_buyer_count_text / cross_border_buyer_count_text（回头客数、跨境买家数原文，如 300+）、response_rate（响应率 0-1）、positive_review_rate（好评率 0-1）、fulfillment_rate（履约率 0-1）、certificate_count / certificates / management_certificates（证书数、证书名、管理体系认证）、patent_count（专利数）、oem_mode（OEM/ODM）、own_brands（自有品牌原文）、brand_count、partner_brand（合作品牌）、is_major_brand_partner（是否大牌供应商）、scale_tier（规模档，如 规上企业）、honors（荣誉）。商品详情同步调用时可能为空；异步调用通常有值。 |
| supplier_scores | 供应商分项服务分（1-5，没有评分的项不给）：goods（商品）、logistics（物流）、consultation（咨询）、dispute（纠纷）、return（退换货）；综合分见 supplier_composite_score。 |
| supplier_metric_tags | 工厂指标标签：[{name, value}]，如 回头率 66%、履约率 100%。 |
| supplier_rank | 供应商上榜信息：text（如 2026上榜二钻工厂）、link_url（榜单页）。 |
| supplier_industry_belt | 产业带认证：description（如 1688官方认证的安阳连身衣产业带旗舰商家）、link_url（认证说明页）。商品详情同步调用时可能为空；异步调用通常有值。 |
| supplier_certification | 第三方验厂/验商认证：agency（认证机构代码，如 sgs、tuv）、report_number（报告编号原文）、report_url（报告页）。商品详情同步调用时可能为空；异步调用通常有值。 |
| supplier_verification_tags | 供应商认证标签，如 深度验厂、深度验商。 |
| supplier_inspection_report_url | 验厂/验商报告页链接。 |
| supplier_videos | 工厂/公司视频：video_id、title、type（视频类型代码）、video_url、cover_url、duration_sec（秒）。 |
| supplier_address | 供应商地址原文。商品详情同步调用时可能为空；异步调用通常有值。 |
| supplier_coordinates | 供应商位置坐标：{longitude（经度）, latitude（纬度）}。商品详情同步调用时可能为空；异步调用通常有值。 |
| supplier_main_category | 供应商主营类目。商品详情同步调用时可能为空；异步调用通常有值。 |
| customization | 定制服务（只含有值的子键）：title（定制说明）、lead_time_days（定制交期，天）、min_order_quantity / min_order_unit（定制起订量与单位）、services（可定制项，如 更换客户标）、options（定制选项：service 选项名、selection 单选/多选、choices[] 每个选择的 name、description、is_default、min_value / max_value / unit（尺寸类取值范围）、image_url、price_tiers[{min_quantity, price}] 加价阶梯）。是否支持定制看 customization_supported。 |
| shipping | 物流（只含有值的子键）：carrier（常用快递）、logistics_text（物流说明原文）、dispatch_hours / dispatch_text（预计发货时长与说明）、delivery_days / delivery_hours（预计送达时长）、fee（运费，元）、is_free_shipping（是否包邮）、ship_from（发货地）、ship_from_code（发货地行政区划代码）、fee_note（运费说明）。 |
| unit_weight_kg | 单件重量（千克）。商品详情同步调用时可能为空；异步调用通常有值。 |
| platform | 数据来源平台标识，与请求里的 platform 一致（如 xiaohongshu、tiktok）。 |

## Example

```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": "不锈钢保温杯"
  }
}'
```

```python
import os
import requests

response = requests.post(
    "https://api.everyinfra.com/api/v1/social",
    headers={"Authorization": f"Bearer {os.environ['EVERYINFRA_API_KEY']}"},
    json={
        "platform": "alibaba1688",
        "action": "search",
        "params": {
            "keyword": "不锈钢保温杯",
        },
    },
    timeout=120,
)
print(response.status_code)
print(response.json())
```

## Response example

Real response to the example request above, captured 2026-10-13T04:57:06Z. `results` and `count` are real with personal information (names, handles, avatars, profile links, contact details) removed; the list keeps the first 2 of 20. `id`, `billing` and `quota` differ on every call, so only their shape is shown.

```text
{
  "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": { … }
}
```

## FAQ

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

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

### `city` 是什么意思？

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

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

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

## Also

- Capability catalog (no key): https://api.everyinfra.com/api/v1/social/catalog?platform=alibaba1688
- OpenAPI: https://everyinfra.com/openapi.json · Agents guide: https://everyinfra.com/agents.md
