1688 APIs.1688.com ↗
Search 1688.com wholesale products, fetch SKU pricing tiers, variant details, and customer reviews via 4 endpoints. Ideal for supplier research and price comparison.
What is the 1688 API?
The 1688.com API exposes 4 endpoints covering product search, detailed SKU data, customer reviews, and reverse image search across China's primary wholesale B2B marketplace. The search_products endpoint returns up to 40 listings per page with seller login IDs, pricing, and geographic data. The get_product_detail endpoint returns full SKU variant trees, per-tier pricing, and stock information for any offer ID.
curl -X GET 'https://api.parse.bot/scraper/aa6e2b5e-7963-46f5-a6c2-e326775ceae4/search_products?page=1&query=ceramic+mug' \ -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 s-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.
"""Walkthrough: 1688.com Product API — search, drill into details and reviews."""
from parse_apis._1688_com_Product_API import Alibaba1688, NotFoundError
client = Alibaba1688()
# Search for products — limit= caps total items fetched across all pages.
for item in client.product_summaries.search(query="ceramic mug", limit=5):
print(item.title, item.price, item.image_url, item.city)
# Drill into one result for full SKU detail.
first = client.product_summaries.search(query="LED light", limit=1).first()
if first:
detail = first.details()
if detail.sku_model and detail.sku_model.sku_selector_biz_model:
biz = detail.sku_model.sku_selector_biz_model
print(detail.offer_id, biz.sku_price_scale)
if biz.sku_props:
for prop in biz.sku_props:
print(prop.prop, [v.name for v in prop.value])
# Fetch reviews for a product via the sub-resource.
if first:
for review in first.reviews.list(login_id=first.login_id, limit=3):
print(review.star_level, review.content)
# Direct product detail lookup by offer_id.
try:
product = client.products.get(offer_id="1027530641922")
print(product.offer_id)
except NotFoundError as exc:
print(f"Product not found: {exc}")
print("exercised: product_summaries.search / details / reviews.list / products.get")
Full-text search over 1688.com product listings by keyword. Returns a paginated list of product offers with seller info, pricing, and location. Each page returns up to 40 items. Paginates via integer page counter. Results include enough seller context (loginId) to drill into reviews.
| Param | Type | Description |
|---|---|---|
| page | integer | Page number for pagination |
| queryrequired | string | Search keyword (Chinese or English) |
{
"type": "object",
"fields": {
"page": "integer current page number",
"items": "array of product objects with offerId, title, price, imageUrl, loginId, sellerName, bookedCount, province, city, url",
"total": "integer total number of results",
"hasMore": "boolean indicating if more pages are available"
},
"sample": {
"data": {
"page": 1,
"items": [
{
"url": "https://detail.1688.com/offer/1027530641922.html",
"city": "梁山县",
"price": "3.9",
"title": "11oz热升华空白涂层杯 欧美AAA级Sublimation Mug热转印马克杯",
"loginId": "梁山晟恒科贸",
"offerId": 1027530641922,
"province": "山东",
"sellerName": "梁山晟恒科贸有限公司",
"bookedCount": "6"
}
],
"total": 2000,
"hasMore": true
},
"status": "success"
}
}About the 1688 API
Endpoints and Data Shape
The API covers four operations against 1688.com listings. search_products accepts a query string (Chinese or English) plus an optional page integer and returns an array of product objects — each with offerId, title, price, imageUrl, loginId, sellerName, bookedCount, province, city, and url — alongside a total count and hasMore flag for pagination. The loginId field is the key that links search results to reviews.
Product Detail and SKU Data
get_product_detail takes a single offer_id (the numeric string from offerId in search results) and returns the full skuModel object. This includes skuSelectorBizModel with skuPriceScale (quantity-based pricing tiers), skuProps (color, size, and other variant axes with per-option images), stock levels, minimum order quantities, and any active promotion metadata. This is the primary endpoint for supplier price comparison at scale.
Reviews and Image Search
get_product_reviews requires both offer_id and login_id together — neither alone is sufficient. It returns a paginated reviews array where each item may include a star rating, text content, and date. The array can be empty for products with no review activity. search_by_image accepts a publicly accessible image_url and returns visually matching wholesale listings with the same field set as keyword search: offerId, title, price, shopName, loginId, province, city, bookedCount, and url.
The 1688 API is a managed, monitored endpoint for s.1688.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when s.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 s.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?+
- Aggregate wholesale supplier options for a product category using
search_productswith keyword queries and comparingpriceandbookedCountfields. - Build a supplier comparison tool that pulls
skuPriceScalefromget_product_detailto show quantity-break pricing across multiple sellers. - Cross-reference
provinceandcityfields from search results to filter suppliers by manufacturing region. - Feed product images from competitors or retail sites into
search_by_imageto find equivalent wholesale sources on 1688.com. - Monitor review sentiment for a supplier's listings using
get_product_reviewsand thelogin_idobtained from search results. - Enumerate SKU variant options via
skuPropsin the detail endpoint to verify a supplier carries specific colors or sizes before contacting them. - Automate sourcing pipelines that combine keyword search, SKU detail extraction, and review checks in a single workflow.
| 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 `get_product_detail` return beyond basic price and title?+
skuModel structure, which includes quantity-tiered pricing via skuPriceScale, all variant dimensions (colors, sizes, and custom properties) with images in skuProps, stock levels, minimum order quantities, and any promotion or trade-model metadata. This is notably more granular than what search_products returns for the same listing.Can I retrieve seller store profiles or shop-level metrics?+
loginId, sellerName, shopName) and product-level data, but does not have a dedicated endpoint for shop pages, seller ratings, or aggregate transaction history. You can fork this API on Parse and revise it to add a seller-profile endpoint.Why does `get_product_reviews` require both `offer_id` and `login_id`?+
search_products call via the offerId and loginId fields on each item.Does the API support filtering search results by price range, minimum order quantity, or certification?+
search_products endpoint accepts a keyword query and pagination page parameter only — there are no server-side filter parameters for price range, MOQ, or supplier certifications. Filtering on those dimensions must be done client-side using the fields returned in the response. You can fork this API on Parse and revise it to expose additional filter parameters if the underlying source supports them.