1688 APIglobal.1688.com ↗
Search and browse 1688.com wholesale listings by keyword or category. Returns product titles, prices, seller names, images, and sales volume for up to 2000 results.
What is the 1688 API?
The 1688.com Global API covers 2 endpoints for searching and browsing Alibaba's wholesale marketplace. The search_products endpoint accepts Chinese or English keywords and returns up to 20 listings per page — each with price, seller name, province, city, sales volume, and product URL — against a result pool capped at 2000 matches. A second endpoint, get_category_products, browses the same fields by numeric category ID.
curl -X GET 'https://api.parse.bot/scraper/87cc17b9-a363-4c5e-9ddf-61e6e9787e8a/search_products?page=1&query=bluetooth+speaker&category=122708008' \ -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 global-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: Ali1688 SDK — bounded, re-runnable; every call capped."""
from parse_apis.global_1688_com_api import Ali1688, ParseError
client = Ali1688()
# Search for bluetooth speakers on 1688
for product in client.products.search(query="bluetooth speaker", limit=3):
print(product.title, product.price, product.seller_name)
# Browse a specific category (311 = general merchandise)
for product in client.products.by_category(category_id="311", limit=3):
print(product.offer_id, product.title, product.city)
# Drill down: get first result from a filtered search
item = client.products.search(query="usb cable", category="122708008", limit=1).first()
if item:
print(item.offer_id, item.title, item.price, item.product_url)
# Handle errors
try:
for p in client.products.by_category(category_id="999999999", limit=1):
print(p.title)
except ParseError as e:
print(f"error: {e}")
print("exercised: products.search, products.by_category")
Full-text keyword search across 1688.com wholesale listings. Supports optional category filtering. Results are auto-iterated across pages; each page returns up to 20 products with title, price, seller name, image, and sales volume.
| Param | Type | Description |
|---|---|---|
| page | integer | Page number for pagination, 1-based. |
| queryrequired | string | Search keywords (e.g. 'bluetooth speaker', 'phone case'). Chinese or English. |
| category | string | Optional 1688 category ID to filter results (e.g. '122708008' for computer peripherals). Obtainable from get_category_products or the site's category navigation. |
{
"type": "object",
"fields": {
"total": "integer total number of matching products (capped at 2000 by the platform)",
"products": "array of product listings with offer_id, title, price, image_url, seller_name, product_url, sold_count, province, city"
},
"sample": {
"data": {
"total": 2000,
"products": [
{
"city": "深圳市",
"price": "26",
"title": "跨境TG117音响蓝牙音箱便携式插卡音响低音炮户外家用蓝牙小音箱",
"offer_id": "787239771343",
"province": "广东",
"image_url": "https://cbu01.alicdn.com/img/ibank/O1CN01yhGKae1IPNYbaSbcE_!!3703270885-0-cib.jpg",
"sold_count": "已售3.1万+件",
"product_url": "https://detail.1688.com/offer/787239771343.html",
"seller_name": "深圳市安科达锐电子有限公司"
}
]
},
"status": "success"
}
}About the 1688 API
What the API Returns
Both endpoints return an array of wholesale product listings under a products key, alongside a total integer indicating how many results the platform matched (hard-capped at 2000). Each listing carries nine fields: offer_id, title, price, image_url, seller_name, product_url, sold_count, province, and city. This gives you enough to compare supplier pricing, gauge demand via sold_count, and resolve seller geography down to city level.
Endpoints in Detail
search_products requires a query string and accepts an optional category parameter (a numeric 1688 category ID such as 122708008 for computer peripherals) to narrow results to a single product vertical. Pagination is controlled by the integer page parameter, 1-based, with up to 20 products returned per page. Both Chinese-character queries and romanized English terms are accepted.
get_category_products takes a required category_id string — for example 311 for general merchandise — and the same optional page parameter. It returns the identical nine-field product listing shape as search_products, making it straightforward to switch between keyword-driven discovery and category browsing without reformatting responses.
Coverage and Scope
All listings originate from 1688.com, which is Alibaba's domestic China wholesale platform aimed at bulk buyers. Prices are in RMB. Seller locations reflect the province and city fields, which are useful for estimating shipping origin. The 2000-result cap per query is a platform-level constraint, not a pagination limit — you can walk pages up to that ceiling but cannot retrieve result 2001 onward.
The 1688 API is a managed, monitored endpoint for global.1688.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when global.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 global.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 comparison tool using
priceandseller_nameacross multiple keyword searches - Monitor
sold_counttrends for a product category to identify fast-moving SKUs - Aggregate supplier geography using
provinceandcityfields to map sourcing concentration - Populate a product catalog with 1688 listings, images, and direct
product_urllinks for buyer review - Filter category-specific inventory using
get_category_productswith known category IDs - Cross-reference
offer_idvalues over time to track listing availability and price changes
| 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 `search_products` endpoint return, and how does category filtering work?+
offer_id, title, price, image_url, seller_name, product_url, sold_count, province, and city, plus a total count. You can optionally pass a category parameter with a numeric 1688 category ID to restrict results to one product vertical. Category IDs are not embedded in the response — you need to supply them from an external reference or prior knowledge.Why does the result count cap at 2000?+
category parameter or more specific keywords can help surface the most relevant results within that window.Does the API return individual product detail pages, reviews, or seller ratings?+
Are the prices returned in a specific currency, and do they reflect MOQ tiers?+
price field per listing and does not break down minimum order quantity (MOQ) tiers or bulk pricing brackets. You can fork this API on Parse and revise it to capture tiered pricing data if that detail is needed.