1688 APIopen.1688.com ↗
Fetch 1688.com product details — name, images, tiered CNY prices, SKUs, variations, and seller info — from a single product URL via the get_product endpoint.
What is the 1688 API?
The open.1688.com API exposes 1 endpoint, get_product, that resolves any 1688.com product URL into a structured record containing 12 response fields: product title, main images, video, quantity-tiered prices in Chinese yuan, full SKU list with stock and sales counts, variation options (colour, size, model), product attributes, seller identity, shipping origin, listing status, and leaf category. An optional exchange_rate parameter converts all prices to Nigerian naira automatically.
curl -X GET 'https://api.parse.bot/scraper/e369c105-7283-4400-aeac-cb36566ee2dc/get_product?product_url=https%3A%2F%2Fdetail.1688.com%2Foffer%2F1037330040237.html&exchange_rate=215.5' \ -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 open-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 Product Lookup — fetch a product, inspect pricing and SKUs."""
from parse_apis.open_1688_com_api import Open1688, ProductNotFound
client = Open1688()
# Fetch a product with naira conversion at a caller-supplied exchange rate.
try:
product = client.products.get(
product_url="https://detail.1688.com/offer/1037330040237.html",
exchange_rate=215.5,
)
except ProductNotFound:
print("Product no longer exists on 1688")
raise SystemExit
print(product.title, f"({product.category})")
print(f"Price: ¥{product.price_min_cny}–¥{product.price_max_cny}")
print(f"Stock: {product.total_stock} {product.unit}, MOQ {product.min_order_quantity}")
# Walk wholesale price tiers.
for tier in product.price_tiers:
cap = f"–{tier.max_quantity}" if tier.max_quantity is not None else "+"
print(f" {tier.min_quantity}{cap}: ¥{tier.price_cny}", end="")
if tier.price_ngn is not None:
print(f" / ₦{tier.price_ngn}", end="")
print()
# Show variation options (e.g. colour, length).
for opt in product.options:
names = [v.name for v in opt.values]
print(f"Option '{opt.name}': {', '.join(names)}")
# Inspect first SKU's attributes and stock.
if product.skus:
sku = product.skus[0]
print(f"SKU {sku.sku_id}: {sku.spec}, stock={sku.stock}, sold={sku.sales_count}")
# Seller info.
print(f"Seller: {product.seller.company_name} — {product.seller.shop_url}")
print("exercised: products.get")
Fetches one 1688.com product (offer) from its public product page and returns the name, main images, video, quantity-tiered prices in Chinese yuan, variation options and SKUs, product attributes, shipping origin and seller. Text fields (title, option names, attribute names) are returned in Chinese exactly as the site publishes them. Prices are CNY numbers; when exchange_rate (naira per 1 yuan) is supplied every *_ngn field is the matching CNY value multiplied by that rate and rounded to 2 decimals, otherwise every *_ngn field and exchange_rate are null. price_tiers is the wholesale quantity ladder (min_quantity/max_quantity inclusive, max_quantity null on the last tier). Per-SKU prices are not published to visitors who are not signed in, so skus[*].price_cny is null whenever the site hides them (observed on every product tested); use the product-level price_min_cny/price_max_cny/price_tiers instead. skus[*].attributes maps each option name to that SKU's chosen value. One page fetch per call; the site rate-limits product-page views per network address, so a call may be answered with a blocked status and should simply be retried. A product id that no longer exists returns stale_input (input_not_found); a value that is not a 1688 product link or numeric id returns stale_input (input_format_invalid).
| Param | Type | Description |
|---|---|---|
| product_urlrequired | string | A 1688 product link containing /offer/<numeric id> (query strings are ignored), or the bare numeric product id itself. The same id is echoed back as product_id. |
| exchange_rate | number | Configured conversion rate expressed as Nigerian naira per 1 Chinese yuan (must be positive). When omitted no naira values are computed. |
{
"type": "object",
"fields": {
"skus": "array of {sku_id, spec_id, spec, attributes{option name: value}, price_cny (null when hidden), price_ngn, stock, sales_count}",
"unit": "selling unit label (Chinese)",
"title": "product name as published (Chinese)",
"images": "array of full-size main image URLs",
"seller": "object {company_name, shop_url}",
"status": "site listing status string, e.g. PUBLISHED",
"options": "array of variation dimensions {name, unit, values:[{name, image}]} such as colour and size",
"category": "leaf category name",
"currency": "always CNY; the currency the *_cny prices are in",
"video_url": "main product video URL or null",
"attributes": "array of {name, value} product specification attributes",
"product_id": "string numeric 1688 offer id",
"ships_from": "shipping origin city (Chinese)",
"price_tiers": "array of {min_quantity, max_quantity (null = no upper bound), price_cny, price_ngn} wholesale quantity tiers",
"product_url": "canonical product page link",
"total_stock": "total orderable quantity across SKUs (integer)",
"video_cover": "video cover image URL or null",
"exchange_rate": "the naira-per-yuan rate applied, null when none given",
"price_max_cny": "highest product price in yuan (number)",
"price_max_ngn": "price_max_cny converted at exchange_rate, null when no rate given",
"price_min_cny": "lowest product price in yuan (number)",
"price_min_ngn": "price_min_cny converted at exchange_rate, null when no rate given",
"shipping_note": "seller's dispatch promise text",
"min_order_quantity": "minimum order quantity (integer)",
"price_display_type": "site pricing mode: rangePrice (quantity tiers) or skuPrice (per-SKU, hidden to visitors)"
},
"sample": {
"data": {
"skus": [
{
"spec": "日月战>3.6",
"stock": 3000,
"sku_id": "6051861032924",
"spec_id": "02433c98a626eee388e4bc0f9da70246",
"price_cny": null,
"price_ngn": null,
"attributes": {
"长度": "3.6",
"颜色": "日月战"
},
"sales_count": 0
}
],
"unit": "个",
"title": "厂家供货多款溪流竿碳素手竿超轻硬短节鱼竿钓鱼竿实体款",
"images": [
"https://cbu01.alicdn.com/img/ibank/O1CN01R8hEq01SdFnqz4jsj_!!2222097782269-0-cib.jpg"
],
"seller": {
"shop_url": "https://shop965072y7v22l6.1688.com",
"company_name": "献县琪艺渔具厂(个体工商户)"
},
"status": "PUBLISHED",
"options": [
{
"name": "颜色",
"unit": null,
"values": [
{
"name": "日月战",
"image": "https://cbu01.alicdn.com/img/ibank/O1CN01LVTrXo1SdFnmJu07y_!!2222097782269-0-cib.jpg"
}
]
},
{
"name": "长度",
"unit": "m",
"values": [
{
"name": "3.6",
"image": null
},
{
"name": "4.5",
"image": null
}
]
}
],
"category": "鱼竿",
"currency": "CNY",
"video_url": "https://cloud.video.taobao.com/play/u/2222097782269/p/2/e/6/t/1/558176644869.mp4",
"attributes": [
{
"name": "产品类别",
"value": "溪流竿"
},
{
"name": "材质",
"value": "碳素"
}
],
"product_id": "1037330040237",
"ships_from": "河北省沧州市",
"price_tiers": [
{
"price_cny": 3,
"price_ngn": 646.5,
"max_quantity": null,
"min_quantity": 1
}
],
"product_url": "https://detail.1688.com/offer/1037330040237.html",
"total_stock": 44997,
"video_cover": "https://img.alicdn.com/imgextra/i3/6000000005915/O1CN01vKrgSf1tZ7rJcAGFI_!!6000000005915-0-tbvideo.jpg",
"exchange_rate": 215.5,
"price_max_cny": 3,
"price_max_ngn": 646.5,
"price_min_cny": 3,
"price_min_ngn": 646.5,
"shipping_note": "承诺48小时发货·常发中通快递",
"min_order_quantity": 1,
"price_display_type": "skuPrice"
},
"status": "success"
}
}About the 1688 API
What get_product Returns
The get_product endpoint accepts either a full 1688.com product link (anything containing /offer/<numeric id>) or the bare numeric offer ID as product_url. It returns a title in Chinese, an images array of full-size URLs, a video_url (or null when none exists), and a currency field that is always CNY to confirm the denomination of all price fields.
SKUs, Variations, and Pricing
The skus array is the core of the response. Each element carries a sku_id, a human-readable spec, an attributes object mapping option names to values (e.g. {"Color": "Red", "Size": "XL"}), price_cny (null when the seller hides individual SKU pricing), price_ngn (populated only when exchange_rate is supplied), stock, and sales_count. The options array describes variation dimensions — each with a name, unit, and values list that includes per-value images where the seller has uploaded swatch photos.
Seller and Listing Metadata
The seller object returns company_name and shop_url so you can link back to the supplier's storefront. The status field reflects the live listing state (e.g. PUBLISHED), and category gives the leaf category name, useful for organizing imports into your own catalog taxonomy. The unit field carries the Chinese selling-unit label (件, 箱, etc.) as the seller has set it.
Currency Conversion
Passing a positive exchange_rate value (naira per yuan) causes every SKU's price_ngn to be populated with the converted amount. No conversion is applied when the parameter is omitted, and price_cny remains the authoritative price field in all cases.
The 1688 API is a managed, monitored endpoint for open.1688.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when open.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 open.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?+
- Import 1688.com product listings into a Nigerian e-commerce storefront with naira pricing pre-calculated via exchange_rate.
- Build a sourcing tool that checks live stock levels per SKU before placing wholesale orders.
- Sync variation options (colours, sizes, models) and their swatch images into a product configurator.
- Display tiered quantity pricing to buyers so they can see volume discount breakpoints from price_cny.
- Validate supplier listings by checking the status field before pushing products to a live catalog.
- Aggregate seller company_name and shop_url to build a vetted supplier directory from browsed product links.
- Extract leaf category and product attributes to auto-classify imported goods into an internal taxonomy.
| 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.