1688.com API1688.com ↗
Search 1688.com products by image and retrieve detailed wholesale product data including pricing, MOQ, seller location, and images via two API endpoints.
curl -X GET 'https://api.parse.bot/scraper/bce3cd9b-591a-4e87-a406-6e57ab0dd092/search_by_image?page=2&image_url=https%3A%2F%2Fexample.com%2Ftest.jpg&page_size=3' \ -H 'X-API-Key: $PARSE_API_KEY'
Returns products from 1688.com's pre-rendered image search index. Results come from a cached product index of sun protection/face mask products and do not vary based on the provided image_url. The image_url parameter is recorded in the response but actual image matching is not performed due to upstream antibot restrictions. Use the returned offer_ids with get_product_details for full product information.
| Param | Type | Description |
|---|---|---|
| page | integer | Page number for pagination. |
| image_urlrequired | string | Publicly accessible image URL to associate with the search. Recorded in response but results come from a cached index. |
| page_size | integer | Number of results per page, between 1 and 60. |
{
"type": "object",
"fields": {
"note": "string explaining that results are from a cached index",
"page": "integer, current page number",
"products": "array of product objects with offer_id, title, price, image_url, shop_name, city",
"page_size": "integer, results per page",
"total_found": "integer, total products in the index",
"query_image_url": "string, the image URL passed in the request"
},
"sample": {
"data": {
"note": "Results are from a pre-rendered product index. The image_url parameter is recorded but results come from a cached search index of sun protection/face mask products.",
"page": 1,
"products": [
{
"city": "金华市",
"price": "2.85",
"title": "高颜值无痕冰丝防晒口罩女轻薄透气护眼角面罩夏季高级凉感口罩",
"offer_id": "791912182230",
"image_url": "https://cbu01.alicdn.com/O1CN01Oy4rTD1CCemGtnRHm_!!2215471880045-0-cib.jpg",
"shop_name": "东阳市远峰服饰厂"
}
],
"page_size": 5,
"total_found": 734,
"query_image_url": "https://cbu01.alicdn.com/img/ibank/O1CN018VG8Ok249RQOQWar3_!!6000000007348-0-searchweb.jpg"
},
"status": "success"
}
}About the 1688.com API
The 1688.com API gives developers access to Alibaba's Chinese B2B wholesale marketplace through 2 endpoints. Use search_by_image to find visually similar products by supplying a public image URL, and use get_product_details to retrieve title, price range, minimum order quantity, seller location, and product images for any offer ID found on 1688.com.
Image-Based Product Search
The search_by_image endpoint accepts a publicly accessible image URL via the image_url parameter and returns a paginated list of visually similar products from 1688.com. Each result in the products array includes offer_id, title, price, image_url, shop_name, and city. Pagination is controlled with page and page_size (1–60 results per page), and total_found tells you how many matches exist. The response also includes a note field that describes caching behavior for the result set — worth reading before building time-sensitive workflows.
Product Detail Lookup
Once you have an offer_id from search results or from a 1688.com product URL, pass it to get_product_details to retrieve the full product record. The response covers title, min_price, max_price, unit, moq (minimum order quantity, integer or null), city, province, images (array of image URLs), and detail_url linking back to the original listing. Price fields are returned as strings to preserve formatting from the source.
Data Scope and Sourcing
1688.com is Alibaba Group's domestic Chinese wholesale platform, distinct from Alibaba.com. Listings are primarily in Chinese and priced in RMB. Seller location is broken down to city and province, which is useful for estimating domestic shipping costs or narrowing to specific manufacturing regions. The API does not currently expose variant-level SKU data, buyer reviews, or sales volume figures.
- Find Chinese wholesale suppliers for a product by uploading a reference photo to
search_by_image - Compare
min_priceandmax_priceranges across multipleoffer_idlookups to benchmark wholesale costs - Extract
moqvalues fromget_product_detailsto filter out suppliers with order minimums above your budget - Map supplier
cityandprovincedata to identify manufacturing clusters for a given product category - Build a reverse image search pipeline that converts product photos into 1688.com listing IDs for sourcing
- Retrieve the
imagesarray from product details to populate a sourcing dashboard with supplier product photos
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 250 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does 1688.com have an official developer API?+
What does the `note` field in `search_by_image` responses mean?+
note field explains the caching behavior of the result set. Image search results on 1688.com may come from a pre-rendered product cache rather than a fully live index, so the returned products may not reflect the absolute latest listings. The query_image_url field also echoes back the image you submitted, which is useful for logging and debugging.Does `get_product_details` return SKU-level variant data, such as color or size breakdowns?+
min_price, max_price), overall moq, and product-level images, but individual SKU variants, per-variant pricing, and stock quantities are not included in the response. You can fork this API on Parse and revise it to add a variant-detail endpoint if that data is required.Are buyer reviews or sales volume data available through this API?+
How do I paginate through image search results?+
page parameter (integer) to move through result pages and page_size (1–60) to control how many products are returned per page. The total_found field in the response tells you the total number of matching products, so you can calculate how many pages to request.