1688 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.
What is the 1688 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.
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'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace 1688-com-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
from parse_apis.alibaba1688_product_search_api import Alibaba1688, Product, ProductSummary
client = Alibaba1688()
# Search for products by image
results = client.productsummaries.search(
image_url="https://cbu01.alicdn.com/img/ibank/O1CN018VG8Ok249RQOQWar3_!!6000000007348-0-searchweb.jpg",
limit=5,
)
for item in results:
print(item.offer_id, item.title, item.price, item.city)
# Get full product details by offer_id
product = client.products.get(offer_id="791912182230")
print(product.title, product.price_display, product.min_price, product.max_price, product.unit)
# Navigate from summary to detail
for summary in client.productsummaries.search(image_url="https://cbu01.alicdn.com/img/ibank/O1CN018VG8Ok249RQOQWar3_!!6000000007348-0-searchweb.jpg", limit=2):
detail = summary.details()
print(detail.offer_id, detail.title, detail.company_name, detail.detail_url)
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
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.
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?+
- 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 | 100 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.