# 1688 Product Detail API (`pizani/1688-product-detail-api`) Actor

Extract detailed product data from 1688, including title, price, reviews, specifications, images, options, and categories. Perfect for market research, e-commerce insights, and data-driven decision-making

- **URL**: https://apify.com/pizani/1688-product-detail-api.md
- **Developed by:** [Pizani](https://apify.com/pizani) (community)
- **Categories:** E-commerce
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $10.00 / 1,000 results

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## 🏭 1688 Product Scraper

This Actor extracts product data from **1688.com** (Alibaba's Chinese wholesale marketplace) and returns a ready-to-use JSON. No browser is used — the data comes from JSON APIs, so runs are fast and cheap.

***

### ✨ What it does

- Accepts a 1688 **product\_url** (or a bare offer ID).
- Extracts **title** (translated + original Chinese), **price** (USD and CNY), **MOQ**, **stock**, **images**, **attributes** and **SKU variants**.
- Collects **store data** (name and ID).
- Pushes the result to the **Dataset** (Output tab).

***

### 🔧 Input

```json
{
  "product_url": "https://detail.1688.com/offer/884771400190.html",
  "resolve_shop_name": true
}
```

| Field | Required | Default | Description |
| --- | --- | --- | --- |
| `product_url` | ✅ | — | Offer URL (`detail.1688.com/offer/<id>.html`) or the bare offer ID. |
| `resolve_shop_name` | ❌ | `true` | Makes one extra request to fill `sellerInfo.shopTitle` (the main API returns it empty for 1688). |

***

### 🧾 Example Output

```json
{
  "sellerInfo": {
    "shopTitle": "佛山市禅城区盈多万服装店",
    "shopID": "BBBN4mn-Ub-019cgQIEf1tAdg",
    "shopLink": null
  },
  "productInfo": {
    "urlproduct": "https://detail.1688.com/offer/884771400190.html",
    "title": "Os Snoopy Spaceship Speedmaster 3861 Multifunctional Chronograph Moon Landing 42m Men's Watch",
    "titleCN": "OS史努比飞船超霸3861多功能计时登月42m男士手表机械表跨境外贸",
    "price": "124.05",
    "priceCNY": "750.0",
    "minOrderQuantity": 1,
    "totalStock": 4,
    "imgList": [
      "https://cbu01.alicdn.com/img/ibank/O1CN014EtQA51x7sfFSBYiw_!!2212305196397-0-cib.jpg",
      "... more images ..."
    ],
    "atributtes": {
      "Brand": "Other",
      "Model": "8215/3861",
      "Movement type": "Machine",
      "Case material": "Stainless steel"
    },
    "options": [
      {
        "name": "Snoopy / 8215 back cover (without spaceship)",
        "imgUrl": "https://cbu01.alicdn.com/img/ibank/O1CN014EtQA51x7sfFSBYiw_!!2212305196397-0-cib.jpg",
        "price": "124.05",
        "priceCNY": "750.0",
        "stock": 199,
        "skuNo": "58cac820dde29a250cd05dbf578c31f3"
      }
    ]
  }
}
```

***

### 🧩 Field Reference

- `sellerInfo.shopTitle`: Store name (original Chinese).
- `sellerInfo.shopID`: Store identifier — on 1688 this is an **opaque hash**, not a numeric ID.
- `sellerInfo.shopLink`: Always `null` on 1688 — the store URL cannot be derived from the hashed ID.
- `productInfo.urlproduct`: Offer URL.
- `productInfo.title` / `titleCN`: Translated title / original Chinese title.
- `productInfo.price` / `priceCNY`: Base price in USD / CNY.
- `productInfo.minOrderQuantity`: Minimum order quantity (MOQ) — 1688 is a wholesale marketplace, so this is often greater than 1.
- `productInfo.totalStock`: Total stock available.
- `productInfo.imgList`: List of image URLs (main image first).
- `productInfo.atributtes`: Map of product attributes (key/value).
- `productInfo.options[]`: SKU variants — `name` (all variation values joined with `/`), `imgUrl`, `price` (USD), `priceCNY`, `stock`, `skuNo`.

***

### ⚠️ 1688 vs Taobao

If you are coming from the Taobao scraper, note these platform differences:

| | Taobao | 1688 |
| --- | --- | --- |
| Shop ID | numeric (`1822521250`) | opaque hash (`BBBN4mn-Ub-…`) |
| Shop link | `shop{id}.taobao.com` | not derivable → `null` |
| MOQ | always 1 | often > 1 (wholesale) |
| SKU naming | single attribute | multiple attributes (colour **+** size) joined with `/` |

***

### 🛠️ How to use via API

```python
import os
import time
import json
import requests

API_TOKEN = "YOUR_APIFY_API_KEY"
ACTOR_ID = "pizani~1688-product-scraper"
PRODUCT_URL = "https://detail.1688.com/offer/884771400190.html"

output_dir = "./scraped_results"
os.makedirs(output_dir, exist_ok=True)
output_file = os.path.join(output_dir, "product_data.json")

run_resp = requests.post(
    f"https://api.apify.com/v2/acts/{ACTOR_ID}/runs?token={API_TOKEN}",
    json={"product_url": PRODUCT_URL}
)

run_data = run_resp.json()
run_id = run_data.get("data", {}).get("id")

if not run_id:
    raise Exception(f"Failed to start Actor: {run_data}")

status_url = f"https://api.apify.com/v2/actor-runs/{run_id}?token={API_TOKEN}"
while True:
    status_resp = requests.get(status_url).json()
    status = status_resp.get("data", {}).get("status")
    if status in {"SUCCEEDED", "FAILED", "ABORTED", "TIMED-OUT"}:
        break
    time.sleep(5)

items_url = (
    "https://api.apify.com/v2/datasets/"
    f"{status_resp['data']['defaultDatasetId']}"
    f"/items?clean=true&format=json&token={API_TOKEN}"
)
result = requests.get(items_url).json()

with open(output_file, "w", encoding="utf-8") as f:
    json.dump(result, f, ensure_ascii=False, indent=4)
```

***

### ℹ️ Notes

- The Actor tries a primary JSON API and automatically falls back to a secondary one, so a single blocked endpoint does not fail the run.
- Fields can vary depending on the product and site availability. Attributes are richer on the primary source.

# Actor input Schema

## `product_url` (type: `string`):

The 1688 offer page URL to scrape (e.g., https://detail.1688.com/offer/884771400190.html). A bare offer ID is also accepted.

## `resolve_shop_name` (type: `boolean`):

1688 offers do not expose the shop name in the main API. When enabled, one extra request is made to fill sellerInfo.shopTitle.

## Actor input object example

```json
{
  "product_url": "https://detail.1688.com/offer/884771400190.html",
  "resolve_shop_name": true
}
```

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "product_url": "https://detail.1688.com/offer/884771400190.html"
};

// Run the Actor and wait for it to finish
const run = await client.actor("pizani/1688-product-detail-api").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "product_url": "https://detail.1688.com/offer/884771400190.html" }

# Run the Actor and wait for it to finish
run = client.actor("pizani/1688-product-detail-api").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"])
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "product_url": "https://detail.1688.com/offer/884771400190.html"
}' |
apify call pizani/1688-product-detail-api --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=pizani/1688-product-detail-api",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/acts/v6v4xRjLfhfVXVnah/builds/X3pDQv0XWYI8lepvS/openapi.json