# 1688 Product Discovery & Listing Monitor (`marketinteltools/china-marketplace-monitor`) Actor

Find target products on 1688, automatically filter accessories and wrong models, and monitor listing changes over time. Built for sourcing, market research, and cross-border e-commerce.

- **URL**: https://apify.com/marketinteltools/china-marketplace-monitor.md
- **Developed by:** [Shi](https://apify.com/marketinteltools) (community)
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $5.00 / 1,000 results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

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

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
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.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## 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.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## 1688 Product Discovery & Listing Monitor

Find target products on **1688.com**, automatically filter accessories and wrong models, and track listing changes over time.

This Actor is designed for sourcing teams, e-commerce sellers, brands, market researchers, and supply-chain analysts who need more than a raw 1688 search scraper.

Instead of returning every search result as-is, the Actor helps identify listings that are actually relevant to a specific brand, model, and product type.

### What does this Actor do?

The Actor performs the following workflow:

1. Searches 1688 using your Chinese search keyword.
2. Collects available product listings.
3. Deduplicates listings by Offer ID.
4. Classifies search results by relevance.
5. Filters common accessories and unrelated products.
6. Detects overly broad model aliases.
7. Saves monitoring history between runs.
8. Detects changes over time.
9. Outputs structured records to an Apify Dataset.

It can be used for:

- Product discovery on 1688
- China sourcing research
- Brand and model monitoring
- Competitor listing monitoring
- Supplier discovery
- Price monitoring
- New listing discovery
- Marketplace research
- Product availability monitoring

***

### Why not use a normal 1688 scraper?

A normal search scraper usually works like this:

```text
keyword
→ search results
→ raw JSON
```

This Actor adds an intelligence layer:

```text
brand + model + product type
            ↓
       1688 search
            ↓
   relevance classification
            ↓
filter accessories / wrong models
            ↓
      monitoring history
            ↓
   change detection events
```

This can reduce the amount of manual work required to review noisy marketplace search results.

***

### Main features

#### Target-based product discovery

Define the product you actually want to monitor using:

- Search keyword
- Brand and brand aliases
- Target model and model aliases
- Product type keywords

The Actor then evaluates each search result against the target.

#### Accessory filtering

1688 search results frequently contain protective cases, cables, adapters, connectors, replacement parts, ear pads, storage bags, stands, and other accessories.

The Actor combines your own exclusion keywords with built-in generic accessory rules.

#### Model alias protection

Short model aliases can create false positives.

For example:

```text
Target:
WH-1000XM5

Unsafe alias:
XM5
```

The short alias `XM5` may also appear in other products such as `WF-1000XM5`.

The Actor can automatically ignore overly broad secondary aliases while preserving the main target model.

#### Persistent monitoring history

Repeated runs can reuse previous monitoring state.

This makes it possible to detect changes instead of treating every run as a completely new scrape.

#### Change detection

The Actor can generate events such as:

- `NEW_TO_US`
- `LISTING_PRICE_CHANGED`
- `TITLE_CHANGED`
- `MATCH_TYPE_CHANGED`
- `POSSIBLY_REMOVED`
- `SEARCH_REAPPEARED`

***

## Input

The easiest way to use the Actor is through the Apify Console input form.

### 1688 Search keyword

The actual keyword sent to 1688 search.

For best results, use a Chinese brand name or product description together with the model when possible.

Example:

```text
索尼 WH-1000XM5
```

### Brand / brand aliases

Brand names that may appear in listing titles.

Separate aliases with `/`, `|`, commas, semicolons, or new lines.

Example:

```text
Sony/索尼
```

### Target model / model aliases

The main model and optional aliases.

Example:

```text
WH-1000XM5/XM5
```

The Actor may automatically ignore secondary aliases that are considered too broad. The first model is treated as the primary model and is preserved.

### Product type keywords

Words describing the actual product type.

Example:

```text
headphones/耳机/头戴式耳机
```

These help distinguish the target product from other products that contain the same model text.

### Accessory / exclusion keywords

Optional words that identify products you do not want to monitor.

Example:

```text
耳机套/保护套/收纳包/数据线/转接头
```

The Actor also includes generic accessory filters automatically.

### Variant keywords

Optional terms that may describe legitimate variants of the target product.

Example:

```text
国行/海外版/商业版
```

### Wrong product-type keywords

Words indicating that a listing belongs to a conflicting product type.

These can help reduce false matches when the same model family appears in multiple product categories.

### Detail-page verification

Detail-page verification is currently not enabled in the public cloud MVP.

The current version primarily uses 1688 search results for discovery and monitoring.

***

## Example input

```json
{
  "searchKeyword": "索尼 WH-1000XM5",
  "brand": "Sony/索尼",
  "model": "WH-1000XM5/XM5",
  "productKeywords": "headphones/耳机/头戴式耳机",
  "accessoryKeywords": "耳机套/耳罩/保护套/保护壳/收纳包/数据线/转接头",
  "variantKeywords": "国行/海外版",
  "productConflictKeywords": "蓝牙音箱/麦克风",
  "enableDetailCheck": false
}
```

***

## Classification

Search results may be classified as:

- **EXACT** — strong match for the target model and product.
- **VARIANT** — relevant variation of the target product.
- **RELATED** — potentially relevant but not the strongest exact match.
- **ACCESSORY** — accessory, replacement component, cable, adapter, storage item, etc.
- **WRONG\_MODEL** — same or similar family but a conflicting model.
- **UNRELATED** — insufficient match to the target.

***

## Output

The Actor stores results in the default Apify Dataset.

There are three main record types:

```text
listing
event
run_summary
```

### Listing record

A `listing` record represents a product currently accepted into the monitoring target.

Example:

```json
{
  "recordType": "listing",
  "targetName": "Sony WH-1000XM5",
  "platform": "1688",
  "offerId": "1067032517840",
  "title": "Sony WH-1000XM5 Premium Wireless Over-Ear Headphones",
  "displayPrice": 263.62,
  "sellerName": "Supplier name",
  "matchType": "EXACT",
  "matchScore": 100
}
```

Typical fields include:

- `recordType`
- `targetName`
- `platform`
- `offerId`
- `title`
- `url`
- `displayPrice`
- `tierMinPrice`
- `sellerName`
- `matchType`
- `matchScore`
- `needsReview`
- `matchReason`
- `runId`
- `capturedAt`

### Event record

An `event` represents a change detected between monitoring runs.

### Run summary

Each run also produces a summary record containing run status, totals, event counts, current target status, matcher profile version, run ID, and capture timestamp.

***

## Event meanings

### NEW\_TO\_US

The listing was discovered by this monitoring target for the first time.

`NEW_TO_US` does **not** mean that the product was newly published on 1688. It only means:

> First seen by this monitor.

### LISTING\_PRICE\_CHANGED

The displayed listing/search price changed compared with the previous recorded state.

This does not necessarily represent the price of every SKU or quantity tier.

### TITLE\_CHANGED

The listing title changed.

### MATCH\_TYPE\_CHANGED

The relevance classification changed.

### POSSIBLY\_REMOVED

A previously monitored listing did not appear in the current search result set.

This does **not** confirm that the listing has been removed from 1688.

Search ranking and marketplace result composition can change between runs.

Therefore `POSSIBLY_REMOVED` means:

> Not found in the current monitored search result set.

It does not mean:

> Confirmed removed from 1688.

### SEARCH\_REAPPEARED

A previously missing listing appeared again in the monitored search results.

***

## Important monitoring semantics

### Search visibility is not listing availability

1688 search rankings can change.

A product can disappear from the current search result set while its detail page remains active.

For that reason, the Actor separates search visibility from confirmed listing availability.

The cloud MVP currently focuses on search visibility monitoring.

***

## Example: filtering noisy 1688 search results

During testing with:

```text
Sony WH-1000XM5
```

a search returned 60 candidate listings.

The matcher classified them approximately as:

```text
ACCESSORY       46
EXACT            1
RELATED          7
UNRELATED        6
```

Only the high-confidence target listing was accepted into the final monitored listing set.

This illustrates the main purpose of the Actor:

> reduce noisy raw marketplace results into a smaller, more relevant monitoring set.

Results will vary depending on the search keyword, product category, seller titles, and current 1688 search results.

***

## Monitoring over time

For meaningful monitoring, run the same target repeatedly.

Typical workflow:

```text
Run 1
→ establish initial listings

Run 2
→ compare with previous state

Run 3+
→ continue detecting changes
```

You can use Apify Tasks and Schedules to automate recurring runs.

***

## Recommended usage

For better matching quality:

1. Use a specific Chinese search keyword.
2. Put the full model first.
3. Avoid overly generic model aliases.
4. Add clear product-type keywords.
5. Add known category-specific accessories when needed.
6. Reuse the same input for recurring monitoring.

Good:

```text
索尼 WH-1000XM5
Sony/索尼
WH-1000XM5
headphones/耳机/头戴式耳机
```

Less precise:

```text
Sony
XM5
electronics
```

***

## Known limitations

This Actor is an MVP and currently has the following limitations:

- Official support is currently focused on 1688.
- Marketplace search rankings can change between runs.
- `POSSIBLY_REMOVED` is not a confirmed delisting signal.
- Cloud detail-page verification is currently disabled.
- Matching uses deterministic classification rules rather than a large language model.
- Complex industrial model families may require more specialized model rules.
- Marketplace titles can contain unusual abbreviations, spelling variations, or SEO keyword stuffing.
- 1688 website or API behavior may change over time.

***

## Pricing

The current price is shown directly on the Actor's Apify Store page.

The Actor uses cloud resources and may use residential proxy traffic while accessing 1688.

Actual run cost depends on runtime, proxy traffic, number of runs, and platform resource consumption.

***

## API and automation

Because this is an Apify Actor, it can be integrated with:

- Apify API
- Apify Tasks
- Apify Schedules
- Webhooks
- External automation workflows

***

## Data and responsible use

This Actor processes publicly accessible marketplace information available during the run.

Users are responsible for using the Actor and resulting data in accordance with applicable laws, marketplace terms, contractual obligations, and their own compliance requirements.

Do not use the Actor to attempt to bypass authentication or access non-public account information.

***

## Support

If you encounter a result that appears incorrectly classified, useful information to provide includes:

```text
Search keyword
Brand
Target model
Offer ID
Listing title
Expected classification
Actual classification
```

***

## Current scope

Current supported marketplace:

```text
1688.com
```

Planned improvements may include:

- Detail-page verification
- Additional alert integrations
- More monitoring automation
- Additional Chinese marketplaces

Future features will be prioritized based on real user demand.

# Actor input Schema

## `searchKeyword` (type: `string`):

The keyword sent to 1688 search. Chinese brand names and specific model numbers usually give better results.

## `brand` (type: `string`):

Brand names or aliases that may appear in listing titles. Separate multiple values with / or |. Example: Sony/索尼

## `model` (type: `string`):

The target model to monitor. Put the full primary model first. Additional aliases can be separated with / or |. Overly broad secondary aliases may be ignored automatically.

## `productKeywords` (type: `string`):

Optional. Words describing the actual target product type. Separate multiple values with / or |.

## `accessoryKeywords` (type: `string`):

Optional. Additional keywords that indicate accessories or products that should normally be excluded. Built-in generic accessory filtering is also applied automatically.

## `variantKeywords` (type: `string`):

Optional. Terms describing legitimate editions or variants of the target product.

## `productConflictKeywords` (type: `string`):

Optional. Keywords indicating that a listing belongs to a conflicting product type.

## `enableDetailCheck` (type: `boolean`):

Detail-page verification is currently disabled in the cloud MVP and is planned for a later version.

## Actor input object example

```json
{
  "searchKeyword": "索尼 WH-1000XM5",
  "brand": "Sony/索尼",
  "model": "WH-1000XM5/XM5",
  "productKeywords": "headphones/耳机/头戴式耳机",
  "accessoryKeywords": "耳机套/保护套/收纳包/数据线/转接头",
  "variantKeywords": "国行/海外版",
  "productConflictKeywords": "蓝牙音箱/麦克风",
  "enableDetailCheck": false
}
```

# Actor output Schema

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

No description

# 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 = {
    "searchKeyword": "索尼 WH-1000XM5",
    "brand": "Sony/索尼",
    "model": "WH-1000XM5/XM5",
    "productKeywords": "headphones/耳机/头戴式耳机",
    "accessoryKeywords": "耳机套/耳罩/保护套/保护壳/收纳包/数据线/转接头",
    "variantKeywords": "国行/海外版",
    "productConflictKeywords": "蓝牙音箱/麦克风",
    "enableDetailCheck": false
};

// Run the Actor and wait for it to finish
const run = await client.actor("marketinteltools/china-marketplace-monitor").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 = {
    "searchKeyword": "索尼 WH-1000XM5",
    "brand": "Sony/索尼",
    "model": "WH-1000XM5/XM5",
    "productKeywords": "headphones/耳机/头戴式耳机",
    "accessoryKeywords": "耳机套/耳罩/保护套/保护壳/收纳包/数据线/转接头",
    "variantKeywords": "国行/海外版",
    "productConflictKeywords": "蓝牙音箱/麦克风",
    "enableDetailCheck": False,
}

# Run the Actor and wait for it to finish
run = client.actor("marketinteltools/china-marketplace-monitor").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 '{
  "searchKeyword": "索尼 WH-1000XM5",
  "brand": "Sony/索尼",
  "model": "WH-1000XM5/XM5",
  "productKeywords": "headphones/耳机/头戴式耳机",
  "accessoryKeywords": "耳机套/耳罩/保护套/保护壳/收纳包/数据线/转接头",
  "variantKeywords": "国行/海外版",
  "productConflictKeywords": "蓝牙音箱/麦克风",
  "enableDetailCheck": false
}' |
apify call marketinteltools/china-marketplace-monitor --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,marketinteltools/china-marketplace-monitor"
        }
    }
}
```

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/aiRv2Es2nhecvgjKw/builds/gXues2W4cxLFhRPQB/openapi.json