1688 API1688.com ↗
Access 1688.com product data via 3 endpoints: keyword search, image search, and detailed product info including SKUs, price ranges, and seller location.
What is the 1688 API?
This API exposes 3 endpoints for retrieving wholesale product data from 1688.com, Alibaba's Chinese B2B marketplace. The get_product_details endpoint returns SKU-level variant data, price ranges, seller location, and product images for any listing identified by its offer ID. The search_by_keyword endpoint supports both Chinese and English search terms, making it practical for cross-language sourcing workflows.
curl -X GET 'https://api.parse.bot/scraper/bce3cd9b-591a-4e87-a406-6e57ab0dd092/search_by_image?page=1&image_url=https%3A%2F%2Fcbu01.alicdn.com%2Fimg%2Fibank%2FO1CN018VG8Ok249RQOQWar3_%21%216000000007348-0-searchweb.jpg&page_size=10' \ -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. 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": 60,
"total_found": 734,
"query_image_url": "https://cbu01.alicdn.com/img/ibank/O1CN018VG8Ok249RQOQWar3_!!6000000007348-0-searchweb.jpg"
},
"status": "success"
}
}About the 1688 API
Endpoints and What They Return
The search_by_keyword endpoint accepts a keywords parameter (Chinese or English), plus optional page and page_size (1–60) controls. Each result in the products array includes offer_id, title, price, image_url, shop_name, city, and province. The has_more boolean and total_found integer make it straightforward to implement pagination over large result sets.
The get_product_details endpoint takes an offer_id — obtainable from search results or directly from a 1688.com product URL — and returns the full listing record: title (in Chinese), min_price and max_price, an images array, moq (minimum order quantity), unit, seller city and province, and a skus array. Each SKU object carries a sku_id, spec_id, and an attributes object that maps dimension names (such as color or size) to their values, enabling programmatic variant handling.
Image Search Behavior
The search_by_image endpoint accepts a publicly accessible image_url and pagination parameters. Due to upstream antibot restrictions, the endpoint does not perform live image matching; results are drawn from a cached index of sun protection and face mask products. The query_image_url field echoes back the URL you submitted, and a note field in the response explicitly documents this limitation. For general product discovery, search_by_keyword is the more versatile option.
Data Coverage
All product titles are returned in Chinese. Price fields (min_price, max_price, individual SKU prices) are strings representing CNY values. Seller geography is broken down to city and province. The API does not require a 1688.com account to retrieve listing or search data.
The 1688 API is a managed, monitored endpoint for 1688.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when 1688.com changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official 1688.com API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Build a wholesale price tracker that monitors
min_priceandmax_pricechanges for specific 1688.com offer IDs over time. - Enumerate SKU variants programmatically using the
skus[].attributesobject to map color and size combinations before placing bulk orders. - Cross-reference supplier geography by filtering
search_by_keywordresults bycityorprovinceto find regional manufacturers. - Aggregate
moqvalues across competing listings to identify suppliers with the lowest minimum order requirements for a given product category. - Translate and index Chinese product titles from
get_product_detailsinto an English-language wholesale catalog. - Feed
offer_idvalues fromsearch_by_keywordintoget_product_detailsto enrich a product comparison table with full image galleries and variant data. - Seed a dropshipping or sourcing tool with paginated keyword search results using
page_sizeup to 60 and thehas_moreflag for loop control.
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 200 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
| Team | $300/mo | 20,000 | 300 req/min |
| Company | $1,000/mo | 100,000 | 500 req/min |
Each endpoint has a fixed posted price per successful call — most fall between 1 and 10 credits — shown on this API's page before you run it. 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 `skus` array in `get_product_details` actually contain?+
sku_id, a spec_id, and an attributes object whose keys are dimension names (for example, '颜色' for color or '尺寸' for size) and whose values are the specific option for that SKU. This lets you reconstruct a variant matrix without parsing free-text descriptions.How does image search work and what are its current limitations?+
search_by_image endpoint records the submitted image_url in the query_image_url response field, but live image-similarity matching is not performed. Results come from a fixed cached index of sun protection and face mask products. The response includes a note field that states this explicitly. If you need broader category coverage, search_by_keyword with relevant terms is more reliable.Does the API return seller reviews, transaction volume, or store ratings?+
Are product titles and attributes returned in English?+
search_by_keyword endpoint accepts English input, but the matched listings will still return Chinese-language titles and attribute names in the response. Translation must be handled in your own application layer.