1688 关键词搜索 API
接口健康状态
- 24h 健康值
- 100%
- 24h 平均耗时
- 12.71 s
- 健康 / 正常
- 可用
- 少量可用
- 基本不可用
24 小时趋势
30 天趋势
关键词搜索:返回列表,默认 20 条、单次最多 100 条;主要字段 id、url、title、text、price_min、price_max。
请求发到 POST https://api.everyinfra.com/api/v1/social,platform 填 alibaba1688,action 填 search。 单价 $2.78 / 千次(每次 $0.002778),失败和空结果都不收费。 同步返回;慢任务可在请求体加 "mode": "async",先拿 job_id 再轮询。
1688 关键词搜索按 keyword 检索批发商品,返回标题、价格区间、最小起订量、销量、复购率、供应商名称与所在地、经营模式和入驻年限、是否缺货和是否支持一件代发。它回答「这个品类在 1688 上有哪些货源、起订和价格大概怎样」,是找供应商、比货源和无货源选品的第一步。
用 min_price、max_price 圈价格,用 city 按城市筛选,用 sort 按相关度、畅销或价格升降排序。采购前先看 min_order_quantity;repurchase_rate 和 supplier_composite_score 可以在打开详情前先筛一遍供应商。价格筛选不保证每个规格和数量档都在区间内,阶梯价以商品详情为准。
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:批发商品价格筛选上限,数值;不是阶梯报价中的采购数量上限。可带小数;个别情况按整元筛选时向上取整(145.98 按 146),只放宽不收窄。
- min_price:批发商品价格筛选下限,数值;不是最低起订量或 API 调用预算。可带小数;个别情况按整元筛选时向下取整(39.81 按 39),只放宽不收窄。不同采购数量可能对应不同阶梯价,不能把筛选价当作最终成交报价。
- 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(城市名);一共 68 个字段,完整列表见 https://api.everyinfra.com/api/v1/social/catalog?platform=alibaba1688。
- 示例请求体:
{
"platform": "alibaba1688",
"action": "search",
"params": {
"keyword": "不锈钢保温杯"
}
}
- 计费:$2.78 / 千次;失败和空结果不扣费。
- 一次要采几十上百个时,在请求体加 "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 | string | 是 | - | 1688 批发商品搜索词,例如保温杯、包装纸盒。用于 search,不是店铺名或 offerId;起订量和阶梯价属于返回的商品信息。 |
city | body.params | string | 否 | - | 1688 商品查询的城市筛选文本。它不是账号所在地,也不会修改返回供应商的地址;指定单品时不能据此推断该筛选仍生效。 |
max_price | body.params | number | 否 | - | 批发商品价格筛选上限,数值;不是阶梯报价中的采购数量上限。可带小数;个别情况按整元筛选时向上取整(145.98 按 146),只放宽不收窄。与 min_price 配合限定价格范围,不能保证每个 SKU 或数量档都处于该范围。 |
min_price | body.params | number | 否 | - | 批发商品价格筛选下限,数值;不是最低起订量或 API 调用预算。可带小数;个别情况按整元筛选时向下取整(39.81 按 39),只放宽不收窄。不同采购数量可能对应不同阶梯价,不能把筛选价当作最终成交报价。 |
sort | body.params | string (enum) | 否 | - | 商品搜索排序:relevance 为相关度,popular 为畅销优先,price_asc / price_desc 为价格升序 / 降序。不传时 search 使用 relevance;排序不等于返回精确销量或成交额。允许值popularprice_ascprice_descrelevance |
limit | body.params | integer (1–100) | 否 | 20 | 这次调用最多返回的条数,整数,1–100;不传按默认值,实际返回可能少于这个数。超过上限会在扣费前返回 422。 |
代码示例
#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。
按批发商品名称检索;不是供应商主页查询。
响应示例
#{ "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 | 商品主图链接,按页面顺序;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)。 |
常见问题
#价格筛选为什么和详情页的价格对不上?
#1688 是阶梯价,采购数量不同单价不同。min_price、max_price 只按搜索页的价格筛选,不保证每个规格、每个数量档都在区间内;最终报价以商品详情里的阶梯价为准。
city 是什么意思?
#它是商品查询的城市筛选条件,不是你的账号所在地,也不会改变返回的供应商地址。要看货源地,请读结果里的 city 和 province。
怎么挑适合一件代发的货源?
#先看 supports_dropship 是否为真,再结合 min_order_quantity 和 is_out_of_stock 判断能否小批量拿货、当前有没有货;repurchase_rate 高、supplier_years 长的供应商通常更稳定。
错误与计费
#- 401
- 缺少 Key 或 Key 无效。
- 402
- 余额不足,先充值。
- 422
- 参数名或取值不对,按错误信息给的候选改;不扣费。
- 429
- 超过每分钟请求上限,按 Retry-After 等待后再试。
- 503
- 暂时无法完成,预扣的费用退回;结果未知时先核对,不要直接重发。
- 200 空结果
- 没有数据,不扣费。