1688 Search API
API health
- 24h health
- Normal
- 24h average time
- —
- Healthy / normal
- Available
- Limited
- Mostly down
Last 24 hours
Last 30 days
List 1688 wholesale offers for a product keyword, with price range, minimum order quantity, order count, repurchase rate and seller details. Neither the sort order nor order_count proves exact sales or a final quote.
1688 Search finds wholesale products by keyword and returns each one's title, price range, minimum order quantity, order count, repurchase rate, supplier name, location, business type and years on the platform, stock status and whether it supports dropshipping. Use it to see which suppliers carry a product and roughly what ordering terms and prices look like: the first step in sourcing, comparing suppliers or picking products for a dropshipping store.
Bound the price with min_price and max_price, filter by city with city, and order with sort (relevance, best-selling, or price up or down). Read min_order_quantity first, since it is the first threshold in wholesale buying; repurchase_rate and supplier_composite_score let you screen suppliers before opening any product. Price filters do not guarantee that every variant and quantity tier falls in range; the tiered prices in product details are what count.
Price $1.39 per 1,000 requests ($0.001389 per call). Failed calls and empty results are not charged. Synchronous. For slow jobs add "mode": "async" to the body, take the job_id and poll.
AI prompt
Paste this into your AI assistant. It already holds this endpoint's parameters, response fields and an example request, so the assistant can ask what you need and then write the scraper.
Please help me write a data collection script with the EveryInfra 1688 Search endpoint (alibaba1688/search).
Endpoint contract:
- Request: POST https://api.everyinfra.com/api/v1/social with the header Authorization: Bearer <API key>. Read the key from the EVERYINFRA_API_KEY environment variable and never hard-code it.
- In the request body, set platform to alibaba1688 and action to search, and put the parameters inside params.
- Required parameters:
- keyword: Specifies the search term for 1688 wholesale products (for example, insulated mugs or cardboard boxes). Use product terms rather than store names or offerIds.
- Optional parameters:
- city: Filters 1688 wholesale item queries by city name text. This filter does not reflect account locations, change returned seller addresses, or guarantee persistent filtering on single-product detail requests.
- max_price: Filters wholesale items by maximum unit price as a numeric value. It operates alongside min_price to bound price ranges rather than tier order quantities, and it may not cover every SKU variant or volume discount tier.
- min_price: Filters wholesale items by minimum unit price as a numeric value. This parameter sets item criteria rather than minimum order quantities or API spend limits, and returned tier pricing varies by order volume.
- sort: Sorts search items by relevance (default for search), popular, price_asc, or price_desc. Sorting criteria do not guarantee exact sales figures or total transaction amounts in the payload. (allowed: popular / price_asc / price_desc / relevance)
- limit: The most rows to return in this call, an integer from 1 to 100. The default applies when you leave it out, and a call can return fewer rows. Larger values return 422 before any charge. (default: 20)
- Returns a list of records. Main fields of each record: id, url, title, text, price_min (Lower bound of the price range), price_max (Upper bound of the price range), currency, min_order_quantity (Minimum order quantity (MOQ)), order_count (Order count), repurchase_rate (Repurchase rate), category, city; 24 fields in total, full list at https://api.everyinfra.com/api/v1/social/catalog?platform=alibaba1688.
- Example request body:
{
"platform": "alibaba1688",
"action": "search",
"params": {
"keyword": "不锈钢保温杯"
}
}
- Price: $1.39 per 1,000 requests; failed and empty results are not charged.
- For dozens or hundreds of targets, add "mode": "async" to the body: you get a job_id at once and poll GET https://api.everyinfra.com/api/v1/jobs/{job_id} for the result.
- On 422, fix the request using the suggested parameter names and allowed values in the error; on 429 or 503, wait for Retry-After and try again.
Before writing code, ask me which targets I need, how many, which fields, and what output format I want; then confirm the plan and the rough cost with me.Request parameters
| Name | In | Type | Required | Default | Description |
|---|---|---|---|---|---|
Authorization | header | string | Yes | - | Bearer followed by your API key. Create it in the console; never put it in a URL or a code repository. |
platform | body | string | Yes | alibaba1688 | Platform identifier, fixed value. |
action | body | string | Yes | search | Capability identifier, fixed value. |
keyword | body.params | Not declared | Yes | - | Specifies the search term for 1688 wholesale products (for example, insulated mugs or cardboard boxes). Use product terms rather than store names or offerIds; minimum order quantities and tier pricing return inside item details. |
city | body.params | Not declared | No | - | Filters 1688 wholesale item queries by city name text. This filter does not reflect account locations, change returned seller addresses, or guarantee persistent filtering on single-product detail requests. |
max_price | body.params | Not declared | No | - | Filters wholesale items by maximum unit price as a numeric value. It operates alongside min_price to bound price ranges rather than tier order quantities, and it may not cover every SKU variant or volume discount tier. |
min_price | body.params | Not declared | No | - | Filters wholesale items by minimum unit price as a numeric value. This parameter sets item criteria rather than minimum order quantities or API spend limits, and returned tier pricing varies by order volume. |
sort | body.params | enum | No | - | Sorts search items by relevance (default for search), popular, price_asc, or price_desc. Sorting criteria do not guarantee exact sales figures or total transaction amounts in the payload.Allowed valuespopularprice_ascprice_descrelevance |
limit | body.params | integer (1–100) | No | 20 | The most rows to return in this call, an integer from 1 to 100. The default applies when you leave it out, and a call can return fewer rows. Larger values return 422 before any charge. |
Code samples
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 definition (JSON)]Samples read the key from the EVERYINFRA_API_KEY environment variable; copied code never contains your key.
Response example
Captured October 13, 2026 at 04:57 (UTC) by calling this API with the parameters in the code sample above. results and count are that call's real response with personal information (names, handles, avatars, profile links, contact details) removed; the list keeps the first 2. id, billing and quota differ on every call, so only their shape is shown.
{
"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": { … }
}Response fields
Business data is in results. The table lists the fields a record can contain; values the platform does not show are never made up.
| Field | Meaning |
|---|---|
id | The record's unique ID on the platform. Unique only within one platform; IDs can repeat across platforms. |
url | Link to the record on the platform. |
title | Title. null when the platform has no titles (for example text-only posts). |
text | Body text with HTML removed, returned in full and never cut short (on a few platforms the list results themselves carry only an excerpt; the platform's field notes say so). |
price_min | Lower bound of the price range. |
price_max | Upper bound of the price range. |
currency | Currency code of the price (for example CNY, USD). If price is present but currency is null, do not assume a currency. |
min_order_quantity | Minimum order quantity (MOQ). The first threshold in 1688 wholesale buying: check it before anything else. |
order_count | Order count. |
repurchase_rate | Repurchase rate. One of the firmest signals of supplier quality on 1688. |
category | Category name in the platform's own taxonomy, not normalized across platforms. |
city | City name in the platform's language, not normalized. |
province | Province where the supplier is based. |
supplier_name | Supplier name. |
is_out_of_stock | Whether the product is out of stock. |
supports_dropship | Whether the supplier ships single units on your behalf (dropshipping). A key filter for selling without holding stock. |
images | Array of image links in the platform's display order; absent when there are no images. |
supplier_type | Supplier business mode (e.g. manufacturer, wholesaler). |
supplier_years | Years the supplier has been on the 1688 platform. |
supplier_shop_url | Supplier shop link. |
supplier_composite_score | Supplier composite service score (1-5). |
sold_count_text | Sales as originally displayed on search rows (Chinese source text, e.g. 100+ sold network-wide). |
service_tags | Service label list on search rows. |
product_badges | Product badge list on search rows (e.g. 7×24H response). |
platform | Source platform identifier, the same as platform in the request (for example xiaohongshu, tiktok). |
FAQ
Why don't filtered prices match the product page?
1688 prices are tiered: the unit price depends on how many you buy. min_price and max_price filter on the price shown in search, without guaranteeing that every variant or quantity tier falls in range. The tiered prices in product details are the actual quote.
What does city filter on?
It filters products by city text. It is not your account's location and does not change the supplier addresses returned; read where goods ship from in each result's city and province.
How do I find suppliers that dropship?
Keep results where supports_dropship is true, then check min_order_quantity and is_out_of_stock to see whether you can order small quantities and whether the item is in stock. A high repurchase_rate and a long supplier_years are useful signs the supplier delivers consistently.
Errors and billing
- 401
- Missing or invalid key. Authentication runs before parameter checks, so unauthenticated requests never see the parameter schema.
- 422
- Wrong parameter name or value. The error lists the parameters and allowed values this capability accepts and the closest match; it happens before any charge.
- 402
- Insufficient balance. Top up first.
- 429
- The account's per-minute request limit was reached (all of its API keys count together; a key's own lower limit applies first). Wait for Retry-After and try again; a rate package in the console raises the limit.
- 503
- Could not complete right now. Any charge for the call goes back to your balance automatically, and the billing receipt in the response states the actual outcome, including when it is not yet known. Do not resend blindly.
- 200 empty
- The request completed without data and is not charged (billing.reason = empty_result_refunded).