# 1688 Sourcing Intelligence — Search + Offer Details (`teamkamkod/cn1688-sourcing-intel`) Actor

1688.com (Alibaba China wholesale) sourcing data: keyword search via mtop HTTP (no login, no proxy — near-zero cost) plus best-effort offer details via rotating residential nodes. Deterministic structured rows for sourcing and dropshipping workflows.

- **URL**: https://apify.com/teamkamkod/cn1688-sourcing-intel.md
- **Developed by:** [Team Kamkod](https://apify.com/teamkamkod) (community)
- **Categories:** E-commerce, Business
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.60 / 1,000 search-results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#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 Sourcing Intelligence — Search + Offer Details

Structured 1688.com (Alibaba China wholesale) sourcing data: **keyword search**
and **product offer details**, no account required. Deterministic output —
built for sourcing / dropshipping / margin workflows and AI agents.

### Two data modes

#### 🔎 Keyword search (mtop gateway — HTTP pure, no proxy)

Chinese wholesale search via 1688's own mobile gateway (signed mtop calls,
guest token). Works from standard datacenter IPs — no browser, no captcha.
Each returned row (charged `search-result`): offerId, clean title, price CNY,
main image, province/city, seller memberId + name, verification flags
(superFactory / business inspection / power merchant), sales proxy, offer URL.

```json
{ "keywords": ["手机壳"], "maxResults": 50, "merchantType": "verifiedMerchant" }
```

#### 📦 Offer details (best-effort — rotating residential nodes)

Full offer page for a list of offerIds (charged `offer-detail` per offer):
title, start price CNY, price tiers, variant colors, sales count, supplier
flags. 1688 rate-limits/anti-bot ("x5sec") is IP-reputation based: **a failed
fetch is retried on a NEW residential node, never on the same one** (a blocked
node stays blocked). `maxOfferAttempts` (default 2) = distinct nodes tried.

```json
{ "offerIds": ["871022139800", "927875250705"] }
```

`offerIds` takes priority: when filled, `keywords` is ignored.

### Pricing (pay-per-event)

| Event | Price | Charged when |
|---|---|---|
| `search-result` | $0.002 | One search result row pushed |
| `offer-detail` | $0.008 | One offer detail row pushed (all node attempts included) |

Runs returning nothing cost nothing. Filters (`merchantType`) only remove rows,
never add charges.

### Honest limitations

- Offer details depend on residential node quality for Alibaba's anti-bot:
  measured ~60-90 % per node class; node rotation on failure is built in, but a
  heavily flagged batch can still fail — failed offers are reported with
  `fetchStatus` (SLIDER/EMPTY/ERR) and are **not charged**.
- Search-level merchant flags are approximate; full badges require the offer row.
- Price tiers in v1 are best-effort from the mobile offer page; some offers only
  expose the starting price (`priceStartCny`).
- 1688 data is China-wholesale oriented; pricing in CNY. Comply with 1688/Alibaba
  Terms and your local regulations.

### Output example (offer detail)

```json
{
  "offerId": "871022139800",
  "title": "适用苹果18ProMax德甲磁吸隐藏式支架手机壳…",
  "priceStartCny": 9.5,
  "priceTiers": [],
  "variantColors": ["黑色", "灰色", "蓝色", "粉色"],
  "salesCount": 21,
  "supplierFlags": []
}
```

### Roadmap

- v1.2: richer SKU/quantity-ladder parse, supplier score unification
- v2: Sourcing Margin Calculator (landed-cost + resale margin, explicit disclaimer)

# Actor input Schema

## `keywords` (type: `array`):

Keyword search on 1688 (English or Chinese; Chinese returns far more results). Ignored when offerIds is filled.

## `offerIds` (type: `array`):

1688 offer ids to fetch as full offer rows (e.g. 871022139800). Takes priority over keywords. Each offer = one offer-detail event; up to maxOfferAttempts distinct residential nodes tried per offer.

## `maxResults` (type: `integer`):

Cap on search-result rows returned (keyword mode).

## `merchantType` (type: `string`):

any = no filter; superFactory = keep only offers flagged 超级工厂 in search results; verifiedMerchant = keep offers carrying at least one verification signal (superFactory / business inspection / power merchant). Approximate at search level — full badges come with the offer detail.

## `maxOfferAttempts` (type: `integer`):

On a failed detail fetch (slider/empty/network), a NEW residential node is tried — never a retry on the same node (a blocked node stays blocked). Default 2.

## `proxyConfiguration` (type: `object`):

Used for offer-detail fetches only (residential rotation). Keep the default Apify residential group.

## Actor input object example

```json
{
  "keywords": [],
  "offerIds": [],
  "maxResults": 50,
  "merchantType": "any",
  "maxOfferAttempts": 2,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ]
  }
}
```

# Actor output Schema

## `results` (type: `string`):

Rows pushed to the run's default dataset. Each item is one search result (kind: search) or one offer detail (offerId + enrichment fields when requested).

## `input` (type: `string`):

The input used for this run.

# 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 = {
    "proxyConfiguration": {
        "useApifyProxy": true,
        "apifyProxyGroups": [
            "RESIDENTIAL"
        ]
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("teamkamkod/cn1688-sourcing-intel").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 = { "proxyConfiguration": {
        "useApifyProxy": True,
        "apifyProxyGroups": ["RESIDENTIAL"],
    } }

# Run the Actor and wait for it to finish
run = client.actor("teamkamkod/cn1688-sourcing-intel").call(run_input=run_input)

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

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

```

## CLI example

```bash
echo '{
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ]
  }
}' |
apify call teamkamkod/cn1688-sourcing-intel --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,teamkamkod/cn1688-sourcing-intel"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/wlwtT3cUqlg70FsJ6/builds/FUefvqEoiNi2TtECs/openapi.json