1688 APIs.1688.com ↗
Search 1688.com wholesale products by keyword or image, fetch SKU pricing tiers, seller trust-pass profiles, category trees, and customer reviews via 6 endpoints.
What is the 1688 API?
The s.1688.com API exposes 6 endpoints covering China's largest B2B wholesale marketplace, letting you run keyword and image-based product searches, retrieve SKU-level pricing tiers and variant data via get_product_detail, pull seller trust-pass profiles, browse the full category tree, and fetch customer reviews — all returning structured JSON without requiring a 1688.com account.
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'
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; paginate with the integer page counter (omitted = page 1), hasMore tells whether another page exists. An optional category_id (a categoryId from list_categories) is applied upstream as a category filter and changes the result set; the site still requires a keyword, so browsing a whole category is done by searching the category title with its category_id. Each item carries loginId (for get_product_reviews), memberId (for get_seller_profile) and offerId (for get_product_detail).
| Param | Type | Description |
|---|---|---|
| page | integer | Page number for pagination |
| queryrequired | string | Search keyword (Chinese or English) |
| category_id | string | Optional 1688 category ID (categoryId from list_categories) used as an upstream filter on the keyword results. Omitted = no category filter. |
{
"type": "object",
"fields": {
"page": "integer current page number",
"items": "array of product objects with offerId (integer), title, price (string), imageUrl, loginId (seller login name, for get_product_reviews), memberId (seller member ID, for get_seller_profile), sellerName, bookedCount (string), province, city, url",
"total": "integer total number of results reported by the site (capped by the site, e.g. 2000)",
"hasMore": "boolean indicating if more pages are available"
},
"sample": {
"data": {
"page": 1,
"items": [
{
"url": "https://detail.1688.com/offer/936595136873.html",
"city": "武义县",
"price": "5.5",
"title": "工厂直销跨境热款16oz双层螺旋杯来图可定制",
"loginId": "ykxiaotai",
"offerId": 936595136873,
"imageUrl": "https://cbu01.alicdn.com/img/ibank/O1CN019vOOg42Leu1tv24Hh_!!945189718-0-cib.jpg",
"memberId": "ykxiaotai",
"province": "浙江",
"sellerName": "永康市笑泰塑料制品厂",
"bookedCount": "6"
},
{
"url": "https://detail.1688.com/offer/1081467166970.html",
"city": "",
"price": "13.5",
"title": "可爱kt猫保温杯女士高颜值桌面咖啡杯子带把手吸管水杯316不锈钢",
"loginId": "永康市易婕工贸有限公司",
"offerId": 1081467166970,
"imageUrl": "https://cbu01.alicdn.com/img/ibank/O1CN01BqQmunaMTMF2R3rs_!!2223022016197-0-cib.jpg",
"memberId": "b2b-2223022016197e22eb",
"province": "",
"sellerName": "永康市易婕工贸有限公司",
"bookedCount": "103"
}
],
"total": 2000,
"hasMore": true
},
"status": "success"
}
}About the 1688 API
Product Search and Discovery
The search_products endpoint accepts a query string (Chinese or English) and an optional category_id from list_categories to narrow results. Each page returns up to 40 items including offerId, title, price, imageUrl, and the seller's loginId. The total field reports the site-level result count (capped at a figure like 2,000), and hasMore tells you whether additional pages exist. For visual sourcing workflows, search_by_image accepts any publicly accessible image URL and returns visually matching wholesale listings with the same core fields plus memberId for seller lookups.
Product Detail and Reviews
get_product_detail takes an offer_id from search results and returns the full SKU model: skuPriceScale for quantity-based pricing tiers, skuProps for color and size options with variant images, trade model fields like minimum order quantity and stock levels, and active promotion data. get_product_reviews requires both offer_id and login_id (the seller's login name from search results) and returns a paginated array of review objects, each containing a star rating, review content, and date where available. Products with no reviews return an empty array.
Seller Profiles and Category Tree
get_seller_profile resolves a member_id to a structured seller card: companyName, bizTypeName (e.g. 生产厂家 for manufacturer), isTp and tpYear for trust-pass membership status and tenure, customerStar (0–5 composite rating), beFavedCount for follower volume, and companyIcons for any certification badges on the shop header. list_categories returns the full 1688.com category tree — around 52 top-level nodes, each with second- and third-level children — or just a subtree when a parent_id is supplied. The categoryId values it returns feed directly into search_products as filters.
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?+
- Build a supplier comparison tool using get_seller_profile to evaluate trust-pass tenure, customer star ratings, and follower counts across multiple vendors.
- Automate wholesale price monitoring with search_products and get_product_detail to track SKU-level pricing tiers and minimum order quantities over time.
- Power a reverse-image sourcing tool using search_by_image to find 1688 wholesale suppliers matching a product photo from any catalog.
- Populate a product catalog with Chinese wholesale listings by iterating list_categories and running search_products filtered by category_id.
- Aggregate customer sentiment for wholesale products by paginating get_product_reviews and extracting star ratings and review content.
- Filter supplier discovery to specific manufacturing types by combining search_products results with bizTypeName from get_seller_profile.
- Build a category browser for a procurement dashboard using list_categories with parent_id to lazily load subtrees on demand.
| 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.