SuperAPI AI Directory
Partner中文AI newsFavorites
Skills1688-product-search

1688-product-search

Data & analytics

View repository

Updated 11-01 21:30

About this skill

1688 Product Search SKILL

Provides complete product search capabilities through the official 1688 Open Platform API, including 9 core interfaces.

Authentication Description

Each Skill has a built-in independent authentication module (scripts/auth.py），does not depend on any external Skill。

The Token cache of all 1688 Skills points to the same fixed path, realizing "independent operation + authentication happens only once".

  • Token cache path: skills/.1688_token_cache.json(shared by all 1688 Skills)
  • After any Skill completes authentication on its first request, other Skills directly reuse the cache
  • Automatically refreshes with refresh_token before the Token expires
  • Supports ALI1688_REFRESH_TOKEN(automatic refresh) and ALI1688_ACCESS_TOKEN(direct use)

Configuration

Set environment variables in the OpenClaw config:

{
 skills: {
 entries: {
 "1688-product-search": {
 env: {
 ALI1688_APP_KEY: "your-app-key",
 ALI1688_APP_SECRET: "your-app-secret", 
 ALI1688_REFRESH_TOKEN: "your-refresh-token"
 }
 }
 }
 }
}

How to obtain AppKey / AppSecret / Token

If you encounter Token-related errors (such as 401, signature failure, Token expiration), follow these steps:

Step 1: Register as a developer & create an application → obtain AppKey + AppSecret

  1. Open 1688 Open Platform, and log in with a 1688 account
  2. Go to Control Center
  3. Click "My Applications" → "Create Application"
  4. Fill in the application information and submit for review
  5. After approval, you can see on the application details page AppKey and AppSecret

Step 2: Subscribe to a solution → obtain API call permissions

  1. Open Cross-border ERP/Independent Site SaaS Digital Solution
  2. Click "Subscribe Now" to bind the solution to your application
  3. Only after successful subscription does the application have permission to call the APIs in the solution

Step 3: User authorization → obtain access_token + refresh_token

  1. Visit the authorization page in a browser (replace YOUR_APPKEY and YOUR_REDIRECT_URI):
https://auth.1688.com/oauth/authorize?client_id=YOUR_APPKEY&site=1688&redirect_uri=YOUR_REDIRECT_URI
  1. Log in with a 1688 account and agree to authorize
  2. The page will redirect to your callback address, and the URL will contain the code parameter
  3. Exchange the code for a Token (short validity period, must be used within 10 minutes):
curl -X POST "https://gw.open.1688.com/openapi/param2/1/system.oauth2/getToken/YOUR_APPKEY" \
-d "grant_type=authorization_code" \
-d "need_refresh_token=true" \
-d "client_id=YOUR_APPKEY" \
-d "client_secret=YOUR_APPSECRET" \
-d "redirect_uri=YOUR_REDIRECT_URI" \
-d "code=授权码"
  1. The returned result contains:
  • access_token — used to call the API (valid for about 10 hours)
  • refresh_token — used to refresh the access_token (valid for about half a year)

Step 4: Configure into environment variables

  • ALI1688_APP_KEY = the application's AppKey
  • ALI1688_APP_SECRET = the application's AppSecret
  • ALI1688_REFRESH_TOKEN = the refresh_token obtained in the previous step (recommended, supports automatic refresh)
  • ALI1688_ACCESS_TOKEN = the access_token obtained in the previous step (backup, must be manually replaced when expired)

Common Token errors and solutions

Error Cause Solution
HTTP 400 refresh failed refresh_token is invalid or has expired Redo Step 3 authorization to obtain a new refresh_token
HTTP 401 unauthorized access_token has expired or is invalid Set ALI1688_REFRESH_TOKEN to enable automatic refresh
签名错误(code=25) AppSecret is incorrect Check whether ALI1688_APP_SECRET matches the app details page
无权限调用 Solution not subscribed Go back to Step 2 to subscribe to the corresponding solution
refresh_token 半年后过期 Token expired naturally Redo Step 3 authorization

Reference links

Usage

1. Category query

# 查询所有一级类目（英语）
python3 scripts/product_search.py category 0

# 查询中文类目
python3 scripts/product_search.py category 0 --language en

2. Multilingual keyword search

# 英文关键词搜索
python3 scripts/product_search.py keyword-search "dress" --country en

# 中文关键词搜索
python3 scripts/product_search.py keyword-search "连衣裙" --country en

# 带筛选条件的搜索
python3 scripts/product_search.py keyword-search "dress" --country en --filter "shipIn48Hours,shipIn24Hours" --sort '{"price":"asc"}'

3. Multilingual image search

Image search supports three methods, in priority order:local image file > imageId > image URL

# 方式一：本地图片文件（推荐）
# 自动压缩（>300KB）→ base64编码 → 上传获取imageId → 图搜
python3 scripts/product_search.py image-search --image-path "/path/to/your/image.jpg" --country en

# 方式二：图片URL（直接用 imageAddress 字段图搜，无需上传）
python3 scripts/product_search.py image-search --image-url "https://example.com/image.jpg" --country en

# 方式三：已有 imageId（由 upload-image 接口返回）
python3 scripts/product_search.py image-search "your_image_id" --country en

# 上传图片获取imageId（单独使用）
python3 scripts/product_search.py upload-image "/path/to/your/image.jpg"

Processing flow when the user sends an image file or screenshot:

⚠️ Note: The 1688 image upload API (product.image.upload) imageBase64 methodonly supports images from the 1688 platform itself, and returns an invalid imageId ("0"）。

Recommended handling strategy:

  1. Ask the user for the image'soriginal source URL
  2. If the URL contains alicdn.com, directly use the imageAddress field for image search (verified to work)
  3. If the URL does not contain alicdn.com, first download it locally, then upload via base64 to try to obtain an imageId; if the imageId is still "0", fall back to imageAddress image search

Local file base64 upload flow (for reference only, limited success rate):

  1. If the image is larger than 300KB, first compress it with Pillow (adjust quality first, then reduce resolution), then base64 encode it
  2. Call the product.image.upload API (uploadImageParam field wrapper, containing imageBase64) to upload
  3. If a valid imageId is returned (not "0"), use the imageId for image search; otherwise fall back to imageAddress image search

Processing flow when the user provides an image URL:

  • Determine the domain of the image URL:
    • Is a alicdn.com domain(e.g. cbu01.alicdn.com、img.alicdn.com , etc.): directly pass the imageAddress field to the image search API, no download needed
    • Not a alicdn.com domain(e.g. images uploaded by the user, images from other e-commerce platforms, etc.): first download the image to a local temporary file, then follow the local file image search flow (compress → base64 → upload → imageId → image search)

4. Multilingual product details

⚠️ Note: This API supports querying only 1 product per call, and does not support batch querying of multiple product IDs.

# 查询单个商品详情
python3 scripts/product_search.py product-detail "offer_id"

5. Multilingual product store search

# 根据商家ID搜索商品
python3 scripts/product_search.py shop-search "seller_open_id" --country en

6. Multilingual product recommendations

# 基于关键词的商品推荐
python3 scripts/product_search.py offer-recommend "keyword" --country en

7. Product pool item retrieval

Retrieve a product list from a business-customized product pool; product pool access permission is required. When paginating, the same taskId。

# 拉取品池商品（offerPoolId 和 taskId 为必填）
python3 scripts/product_search.py pool-pull --pool-id 111 --task-id 1 --page-no 1 --page-size 10

# 指定类目和排序
python3 scripts/product_search.py pool-pull --pool-id 111 --task-id 1 --cate-id 11 --sort-field order1m --sort-type DESC --page-no 1 --page-size 10

Request parameters:

Parameter Type Required Description Example value
--pool-id Long ✅ Product pool ID (business-customized with permission control; obtain it from the connected business. Passing an arbitrary value will cause an error. For sourcing agent procurement, it is recommended to use the keyword search API) 111
--task-id String ✅ Query task ID; for paginated queries, the same taskId must be used consistently (e.g., if the offer pool has 10,000 products and you query 1,000 per page over 10 queries, the same taskId must be passed for all 10 queries) 1
--page-no Integer ✅ Page number 1
--page-size Integer ✅ Number per page 10
--cate-id Long ❌ Category ID 11
--language String ❌ Language, default en en
--sort-field String ❌ Sort field:order1m(sales in the last 1 month) / buyer1m(number of buyers in the last 1 month) order1m
--sort-type String ❌ Sort order:ASC / DESC DESC

Return result structure:

{
  "result": {
    "success": "true",
    "code": "200",
    "result": [
      {
        "offerId": 111111,
        "bizCategoryId": "111111",
        "offerPoolTotal": 122211
      }
    ]
  }
}
Field Type Description Example value
result.success String Whether successful true
result.code String Error code 200
result.result[].offerId Long Product ID 111111
result.result[].bizCategoryId String Institution's category ID 111111
result.result[].offerPoolTotal Integer Total number of products in the pool (returned for every offer) 122211

8. Related product recommendations

# 基于商品ID的相关推荐
python3 scripts/product_search.py related-recommend "offer_id" --country en

9. Upload an image to get an imageId

# 上传本地图片获取imageId
python3 scripts/product_search.py upload-image "/path/to/image.jpg"

Intelligent image compression feature: When the uploaded image file is larger than 300KB, the system will automatically perform intelligent compression to ensure the image size meets the 1688 API requirements. The compression process will:

  • Automatically detect the image format and convert it to JPEG (if needed)
  • Keep the best image quality while controlling the file size within 300KB
  • Temporarily generate the compressed image for upload, and automatically clean up the temporary file after completion
  • Output detailed compression logs (original size → compressed size)

This ensures that regardless of the size of the image provided by the user, a valid imageId can be successfully obtained for subsequent image search operations.

Important notice

Image search trigger

When instructions related to image search such as "image search for the same item", "find the same item", "search for items by image", "image search for the same item" are received, the system will automatically call the image search API (product.search.imageQuery) instead of the keyword search API.

API trigger rules

User intent API to call Description
Image search for the same item, find the same item, search for items by image product.search.imageQuery Image search
Products from the same store, products from the same seller product.search.querySellerOfferList Need to get from product details sellerOpenId
Similar products, related products, related recommendations product.related.recommend Recommended based on product ID; some products may return empty
Product recommendations product.search.offerRecommend Recommended based on keywords
Pull xx offer pool, pull product offer pool, pull products from the product pool pool.product.pull Need to provide offerPoolId and taskId

Product query results must expose the product ID and link

The return results of all product query APIs (keyword search, image search, store search, product recommendations, etc.) must display the following two core fields to the user:

  • offerId(product ID): the unique identifier of the product, which can be used for subsequent operations such as querying product details and related recommendations
  • Product link: prefer to use promotionURL(promotion link with tracking parameters); if not available, use https://detail.1688.com/offer/{offerId}.html

Display format example (Markdown table or list is acceptable):

商品ID: 683381849222
链接: https://detail.1688.com/offer/683381849222.html?fromkv=...（promotionURL）

It is prohibited to display only the product title and price without exposing the product ID and link; users need the product ID for subsequent operations.

Parameter description

General parameters

Parameter Description Default value Optional value
--country / --language Language code en en / ja / ko / ru / vi / es etc.,Not supported zh
--beginPage Start page number 1 Number
--pageSize Number per page 20 Number, maximum 50

Note: When the API parameters include beginPage , pass by default 1; when they include pageSize , pass by default 20; when they include country or language , pass by default en。

⚠️ Important：country and language parametersNeither supports zh(Chinese). Regardless of whether the user asks in Chinese or English, you must pass en(English) as the default value. Passing zh will cause the API to report an error or return abnormal results.

Filter conditions (filter)

Multiple filter conditions are supported; separate multiple conditions with English commas:

  • shipIn24Hours - Ships within 24 hours
  • shipIn48Hours - Ships within 48 hours
  • certifiedFactory - Certified factory
  • isOnePsale - Supports dropshipping
  • new7 - New arrivals in 7 days
  • 1688Selection - 1688 Selected

Example:--filter "shipIn48Hours,certifiedFactory,isOnePsale"

Sort parameters (sort)

Supports sorting by different dimensions:

  • price - Wholesale price
  • rePurchaseRate - Repurchase rate
  • monthSold - Monthly sales

Example:--sort '{"price":"asc"}' or --sort '{"monthSold":"desc"}'

Output format

JSON format, directly returning the raw response data from the 1688 API.

Important note: All product query results will include the product ID (offerId field), which is the unique identifier of the product and can be used for subsequent product detail queries or other operations.

Error handling

  • No mock data is returned on failure: When the API call fails, parameters are incorrect, or a network exception occurs, an error message JSON is returned directly and the program exits
  • Error format：{"error": "具体的错误信息"}
  • Exit code: Returns exit code 1 on failure and 0 on success

Product result field descriptions

For query results from all product list APIs (keyword search, image search, store search, product recommendations, etc.), all of the following available fields must be displayed:

Field Description Required to display
offerId Product ID, unique identifier ✅ Required
subject Product title (Chinese) ✅ Required
subjectTrans Product title (English translation) Display if available
imageUrl Product main image URL ✅ Required
priceInfo.price Wholesale price ✅ Required
priceInfo.promotionPrice Promotional price Display if available
priceInfo.consignPrice Dropshipping price Display if available
monthSold Monthly sales ✅ Required
repurchaseRate Repurchase rate ✅ Required
minOrderQuantity Minimum order quantity Display if available
tradeScore Store rating Display if available
sellerDataInfo.tradeMedalLevel Merchant level (star rating) Display if available
sellerDataInfo.compositeServiceScore Comprehensive service score Display if available
productSimpleShippingInfo.shippingTimeGuarantee Shipping timeliness (24h/48h) Displayed if present
isOnePsale Whether dropshipping (one-piece dropshipping) is supported Displayed when true
isSelect Whether it is 1688 Yanxuan (strict selection) Displayed when true
offerIdentities Product tag list Displayed if present
sellerIdentities Seller tag list Displayed if present

Explanation of tag value meanings (offerIdentities / sellerIdentities)

Tag value Meaning
tp_member TrustPass member
createDate / modifyDate Listing/update time
Product link Prefer promotionURL, otherwise use https://detail.1688.com/offer/{offerId}.html

API endpoint URLs

Endpoint Full URL
Category query POST https://gw.open.1688.com/openapi/param2/1/com.alibaba.fenxiao.crossborder/category.translation.getById/${APPKEY}
Keyword search POST https://gw.open.1688.com/openapi/param2/1/com.alibaba.fenxiao.crossborder/product.search.keywordQuery/${APPKEY}
Image search POST https://gw.open.1688.com/openapi/param2/1/com.alibaba.fenxiao.crossborder/product.search.imageQuery/${APPKEY}
Product details POST https://gw.open.1688.com/openapi/param2/1/com.alibaba.fenxiao.crossborder/product.search.queryProductDetail/${APPKEY}
Store search POST https://gw.open.1688.com/openapi/param2/1/com.alibaba.fenxiao.crossborder/product.search.querySellerOfferList/${APPKEY}
Product recommendations POST https://gw.open.1688.com/openapi/param2/1/com.alibaba.fenxiao.crossborder/product.search.offerRecommend/${APPKEY}
Product pool product retrieval POST https://gw.open.1688.com/openapi/param2/1/com.alibaba.fenxiao.crossborder/pool.product.pull/${APPKEY}
Related recommendations POST https://gw.open.1688.com/openapi/param2/1/com.alibaba.fenxiao.crossborder/product.related.recommend/${APPKEY}
Image upload POST https://gw.open.1688.com/openapi/param2/1/com.alibaba.fenxiao.crossborder/product.image.upload/${APPKEY}

General 1688 API notes

API integration key points

  • Language support: Defaults to using country=en, but returned fields include both Chinese and English
    • Chinese field example: subject
    • English field example: subjectTrans
    • ⚠️ country and language parameters do not support zh, optional values are en / ja / ko / ru / vi / es , etc.,In all cases, pass en
  • Access Token: The access_token generated by the current solution ispermanently validof
  • Filter conditions: Supports multiple product filter conditions (shipping timeliness, certified factory, dropshipping, etc.)
  • Sorting function: Supports sorting by price/repurchase rate/monthly sales, but only effective for the current page

Important limitations

  • Data volume limit: Each query returns at most 2000 products
  • Image search: It is recommended to use only 1688 image URLs; success rates for other domains are unstable
  • Price display: The API returns the original price; marketing prices apply at checkout

Service list mapping

  • sendGoods24H → 24-hour shipping
  • sendGoods48H → 48-hour shipping

API reference documentation

For complete API endpoint and data structure documentation, please refer to references/api.md。