# 1688 Global Product Search Scraper (`lentic_clockss/1688-global-scraper`) Actor
Find verified English 1688 Global product listings with USD price evidence, supplier signals, images, sales text, and auditable search provenance. Detail pages are best-effort only.
- **URL**: https://apify.com/lentic\_clockss/1688-global-scraper.md
- **Developed by:** [kane liu](https://apify.com/lentic_clockss) (community)
- **Categories:** E-commerce, Automation, Developer tools
- **Stats:** 1 total users, 1 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet
## Pricing
from $3.00 / 1,000 verified 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 a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases.
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.
In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js/docs.md):
```bash
npm install apify-client
```
In Python projects, use official [Python client library](https://docs.apify.com/api/client/python/docs.md):
```bash
pip install apify-client
```
In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md):
````bash
# MacOS / Linux
curl -fsSL https://apify.com/install-cli.sh | bash
# Windows
irm https://apify.com/install-cli.ps1 | iex
```bash
In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/integrations/mcp.md).
If your project is in a different language, use 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 Global Product Search Scraper
**Find export-ready 1688 products with English titles, English supplier names, and USD price evidence — in one search.** Instead of handing you a mixed-language catalog or relabelled CNY prices, this Actor keeps only search results that prove the requested English/USD context.
> Architecture: thin Apify Actor → **alibaba-1688-com** Cloud Run worker (HTTPS + API key).
> Worker URL is config (`WORKER_BASE_URL`), not hardcoded-only — migrate the worker by updating Actor env without a code change. Set `WORKER_PROVIDES_PROXY=1` when the worker supplies its own `PROXY_URL`.
Type a product keyword, click Start, and download a structured product table for sourcing, catalog research, price monitoring, or an AI workflow.
### What you can do with it
#### 1. Find products to source
Search a product category such as `phone case`, `women dress`, or `home storage` and compare offers before opening supplier conversations.
You only fill in the keyword and how many verified listings you want:
| Field | What to enter |
|---|---|
| `keyword` | An English product phrase |
| `maxResults` | Number of listings to save |
| `maxPages` | Search pages to inspect |
The result is a clean, exportable table with a product ID, English title, supplier, USD price, images, sales text, and direct listing link.
#### 2. Compare wholesale price signals
Each saved row includes the USD price evidence shown by the 1688 Global search surface. The raw CNY reference price is retained separately when present; it is never relabelled as USD.
This makes it practical to sort a spreadsheet by price, inspect image counts, and shortlist offers without manually converting each product card.
#### 3. Build a supplier shortlist
The search card can include supplier name, supplier identifiers, supplier tenure text, star level, supplier-tag asset, and sales text.
These are search-list signals, not a claim that the Actor has collected a complete supplier profile. Use them to prioritize which offers deserve a manual follow-up.
#### 4. Monitor a category
Run the same keyword on a schedule and compare the exported tables over time. Each row includes the keyword, requested page, position, source endpoint, and capture timestamp, so downstream systems can retain provenance.
#### 5. Feed an AI or automation workflow
Download CSV, JSON, or Excel from Apify, or send the Dataset to Make, n8n, Zapier, Python, or an MCP-enabled agent. The row contract is structured enough for filters such as “USD price below $10” or “supplier has 5 images”.
### How to use — no code required
1. Click **Try for free**.
2. Enter an English keyword.
3. Keep **Use Apify Residential Proxy** enabled and choose `US`.
4. Set a small `maxResults` value for a first run.
5. Click **Start** and open the Dataset when the run finishes.
That is the full workflow: search, wait, download. Start with one result to verify the product category, then increase the output cap.
#### Free Apify plan limits (set by this Actor's developer)
| Limit | Free Apify plan | Paid Apify plan |
| --- | --- | --- |
| Runs of this Actor | **10 runs total** | Unlimited |
| Listings per run (`maxResults`) | **Up to 100** | Up to 100 |
These caps are enforced by the Actor developer (not Apify platform errors). When you hit the 10-run limit, the run finishes gracefully with a clear status message asking you to upgrade.
### What you get back
Every emitted row has passed the Actor’s English/USD acceptance contract. Core fields include:
- **`offerId`** — stable 1688 offer identifier.
- **`title`** and **`sellerName`** — English product and supplier text from the accepted search result.
- **`priceMin`**, **`priceText`**, and **`priceCurrency`** — verified USD pricing evidence.
- **`priceInCny`** and **`cnyToUsdRate`** — separate source/reference evidence when supplied; never a relabelled price.
- **`mainImage`**, **`galleryImages`**, and **`imageCount`** — images shown by the search result.
- **`salesText`**, **`starLevel`**, **`supplierYearsText`**, and **`sellingPoints`** — available card-level commercial signals.
- **`supplierLoginId`**, **`supplierMemberId`**, and **`supplierTagAssetUrl`** — supplier identifiers/assets exposed by the search result.
- **`page`**, **`position`**, **`keyword`**, and **`capturedAt`** — row provenance.
The Actor also writes `INPUT_ECHO`, `RUN_SUMMARY`, and redacted `NETWORK_DIAGNOSTICS` to the default key-value store. These let you audit whether a run used the verified Global-search path without storing cookies, tokens, signatures, or raw browser traffic.
For developers: minimal input
```json
{
"keyword": "phone case",
"maxResults": 20,
"maxPages": 1,
"useApifyProxy": true,
"proxyCountry": "US"
}
````
### Pricing
**Pay only when the Actor starts and when it returns a Dataset item. No subscription.** Platform usage costs are paid by the Actor owner, so the event prices below are the prices you see.
| Event | Price |
|---|---:|
| Actor start | $0.005 per GB of allocated Actor memory (minimum one event) |
| Verified result | $3.00 per 1,000 Dataset items ($0.003 each) |
The result charge is linear: **no output items means no result-item charge.** The Actor charges the platform dataset event after a successful write (`apify-default-dataset-item`, with a legacy fallback). Charge failures are logged and do not erase already-written Dataset rows.
The start event is counted by Apify from allocated memory; for example, a 4 GB run starts at **$0.020**, then adds **$0.003** for each verified Dataset item.
**Free Apify plan:** up to **10 runs** of this Actor and **100 listings per run**. Upgrade to a paid Apify plan for unlimited runs. (Limits set by the Actor developer.)
#### Zero verified listings
If the Global search API returns a **validated English/USD empty page**, the run finishes as **SUCCEEDED** with `resultStatus=VALID_ZERO_RESULTS`, an empty Dataset, and **no result charge**. Check `RUN_SUMMARY.zeroResultNote`.
### Connect to your tools
Use Actor ID `lentic_clockss/1688-global-scraper` in the Apify integration for Make, n8n, Zapier, or your own code. For AI-agent workflows, the Actor can be discovered through the Apify MCP server.
### When to use something else
| If you need... | This Actor is not the right current path |
|---|---|
| SKU-level inventory, product descriptions, price ladders, or full specifications | Detail access is not yet a stable anonymous capability; use a verified detail-data provider or manually validate shortlisted offers. |
| Chinese domestic-market search results | This Actor is intentionally limited to the 1688 Global English/USD search surface. |
| Guaranteed live shipping quotes or supplier verification | Search-card signals are not a substitute for supplier due diligence. |
### Input reference
| Parameter | Default | Description |
|---|---:|---|
| `keyword` | `phone case` | English product keyword. |
| `maxResults` | `20` | Maximum verified English/USD listings to save (1–100). Free plan: also **10 total runs** of this Actor. |
| `maxPages` | `1` | Search pages to observe (1–5). |
| `useApifyProxy` | `true` | Uses Apify RESIDENTIAL unless Actor env `WORKER_PROVIDES_PROXY=1`. |
| `proxyCountry` | `US` | Residential proxy country currently supported by this Actor. |
| `includeDetails` | `false` | Best-effort detail **navigation** only (title/snippet status). Not SKU/attrs/price-ladder extraction. |
| `maxDetailItems` | `1` | When details are enabled, how many rows to open (defaults to 1 if omitted). |
| `workerBaseUrl` | *(env)* | Optional per-run override of the Cloud Run worker origin. Default: Actor env `WORKER_BASE_URL`. |
### FAQ
**Why is a result missing?** The Actor rejects a response if the observed Global-search payload does not prove the requested keyword, English language, USD currency, numeric offer ID, English text, and USD price evidence.
**Can I search in Chinese?** The product contract is English/USD search-list output. Use English keywords for this Actor.
**I'm on the free Apify plan — are there limits?** Yes. Free Apify plan users get **10 runs** of this Actor and **up to 100 listings per run**. These limits are set by the Actor developer (not Apify). When you hit the run cap, the run finishes with a clear status message — it is not a platform bug.
**Why are detail fields limited?** 1688 detail pages can redirect anonymous browser sessions to a login flow. The Actor records that boundary honestly rather than inventing detail data.
**Can I schedule it?** Yes. Create an Apify schedule with the same input and send the Dataset to your preferred automation.
# Actor input Schema
## `keyword` (type: `string`):
English product query, for example phone case. Chinese keywords are rejected.
## `maxResults` (type: `integer`):
Maximum verified English/USD listings to save (1–100). Free Apify plan users are also limited to 10 total runs of this Actor — limits set by the Actor developer.
## `maxPages` (type: `integer`):
International search pages to observe. Stops early when maxResults is reached.
## `includeDetails` (type: `boolean`):
Optional Phase 2: open listing pages for status classification and light page title/snippet only. Does NOT extract SKU, attributes, or price ladders. Login redirects are marked blocked\_login.
## `maxDetailItems` (type: `integer`):
When includeDetails=true, number of emitted search rows to open (default 1). Capped by maxResults.
## `useApifyProxy` (type: `boolean`):
Required on the Apify platform unless Actor env WORKER\_PROVIDES\_PROXY=1 (worker supplies PROXY\_URL). US residential proxy for the Global English/USD surface.
## `proxyCountry` (type: `string`):
Only US is supported for this Actor's Global English/USD contract.
## `workerBaseUrl` (type: `string`):
Override the Cloud Run worker origin for this run. Defaults to Actor env WORKER\_BASE\_URL. Production migrations should update WORKER\_BASE\_URL in Actor settings (no code change).
## Actor input object example
```json
{
"keyword": "phone case",
"maxResults": 20,
"maxPages": 1,
"includeDetails": false,
"maxDetailItems": 1,
"useApifyProxy": true,
"proxyCountry": "US"
}
```
# Actor output Schema
## `results` (type: `string`):
No description
## `inputEcho` (type: `string`):
No description
## `runSummary` (type: `string`):
No description
## `errorSummary` (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 '' with your token
const client = new ApifyClient({
token: '',
});
// Prepare Actor input
const input = {
"keyword": "phone case"
};
// Run the Actor and wait for it to finish
const run = await client.actor("lentic_clockss/1688-global-scraper").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 '' with your token.
client = ApifyClient("")
# Prepare the Actor input
run_input = { "keyword": "phone case" }
# Run the Actor and wait for it to finish
run = client.actor("lentic_clockss/1688-global-scraper").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 '{
"keyword": "phone case"
}' |
apify call lentic_clockss/1688-global-scraper --silent --output-dataset
```
## MCP server setup
```json
{
"mcpServers": {
"apify": {
"command": "npx",
"args": [
"mcp-remote",
"https://mcp.apify.com/?tools=lentic_clockss/1688-global-scraper",
"--header",
"Authorization: Bearer "
]
}
}
}
```
## OpenAPI specification
```json
{
"openapi": "3.0.1",
"info": {
"title": "1688 Global Product Search Scraper",
"description": "Find verified English 1688 Global product listings with USD price evidence, supplier signals, images, sales text, and auditable search provenance. Detail pages are best-effort only.",
"version": "0.2",
"x-build-id": "SwbC0O5HiKkwjU1Gc"
},
"servers": [
{
"url": "https://api.apify.com/v2"
}
],
"paths": {
"/acts/lentic_clockss~1688-global-scraper/run-sync-get-dataset-items": {
"post": {
"operationId": "run-sync-get-dataset-items-lentic_clockss-1688-global-scraper",
"x-openai-isConsequential": false,
"summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
"tags": [
"Run Actor"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inputSchema"
}
}
}
},
"parameters": [
{
"name": "token",
"in": "query",
"required": true,
"schema": {
"type": "string"
},
"description": "Enter your Apify token here"
}
],
"responses": {
"200": {
"description": "OK"
}
}
}
},
"/acts/lentic_clockss~1688-global-scraper/runs": {
"post": {
"operationId": "runs-sync-lentic_clockss-1688-global-scraper",
"x-openai-isConsequential": false,
"summary": "Executes an Actor and returns information about the initiated run in response.",
"tags": [
"Run Actor"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inputSchema"
}
}
}
},
"parameters": [
{
"name": "token",
"in": "query",
"required": true,
"schema": {
"type": "string"
},
"description": "Enter your Apify token here"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/runsResponseSchema"
}
}
}
}
}
}
},
"/acts/lentic_clockss~1688-global-scraper/run-sync": {
"post": {
"operationId": "run-sync-lentic_clockss-1688-global-scraper",
"x-openai-isConsequential": false,
"summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
"tags": [
"Run Actor"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inputSchema"
}
}
}
},
"parameters": [
{
"name": "token",
"in": "query",
"required": true,
"schema": {
"type": "string"
},
"description": "Enter your Apify token here"
}
],
"responses": {
"200": {
"description": "OK"
}
}
}
}
},
"components": {
"schemas": {
"inputSchema": {
"type": "object",
"required": [
"keyword"
],
"properties": {
"keyword": {
"title": "English keyword",
"type": "string",
"description": "English product query, for example phone case. Chinese keywords are rejected.",
"default": "phone case"
},
"maxResults": {
"title": "Maximum results (max 100; free users capped at 100/run)",
"minimum": 1,
"maximum": 100,
"type": "integer",
"description": "Maximum verified English/USD listings to save (1–100). Free Apify plan users are also limited to 10 total runs of this Actor — limits set by the Actor developer.",
"default": 20
},
"maxPages": {
"title": "Maximum pages",
"minimum": 1,
"maximum": 5,
"type": "integer",
"description": "International search pages to observe. Stops early when maxResults is reached.",
"default": 1
},
"includeDetails": {
"title": "Attempt detail page navigation (best-effort)",
"type": "boolean",
"description": "Optional Phase 2: open listing pages for status classification and light page title/snippet only. Does NOT extract SKU, attributes, or price ladders. Login redirects are marked blocked_login.",
"default": false
},
"maxDetailItems": {
"title": "Maximum detail attempts",
"minimum": 0,
"maximum": 20,
"type": "integer",
"description": "When includeDetails=true, number of emitted search rows to open (default 1). Capped by maxResults.",
"default": 1
},
"useApifyProxy": {
"title": "Use Apify Residential Proxy",
"type": "boolean",
"description": "Required on the Apify platform unless Actor env WORKER_PROVIDES_PROXY=1 (worker supplies PROXY_URL). US residential proxy for the Global English/USD surface.",
"default": true
},
"proxyCountry": {
"title": "Proxy country",
"enum": [
"US"
],
"type": "string",
"description": "Only US is supported for this Actor's Global English/USD contract.",
"default": "US"
},
"workerBaseUrl": {
"title": "Worker base URL (optional)",
"type": "string",
"description": "Override the Cloud Run worker origin for this run. Defaults to Actor env WORKER_BASE_URL. Production migrations should update WORKER_BASE_URL in Actor settings (no code change)."
}
}
},
"runsResponseSchema": {
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"actId": {
"type": "string"
},
"userId": {
"type": "string"
},
"startedAt": {
"type": "string",
"format": "date-time",
"example": "2025-01-08T00:00:00.000Z"
},
"finishedAt": {
"type": "string",
"format": "date-time",
"example": "2025-01-08T00:00:00.000Z"
},
"status": {
"type": "string",
"example": "READY"
},
"meta": {
"type": "object",
"properties": {
"origin": {
"type": "string",
"example": "API"
},
"userAgent": {
"type": "string"
}
}
},
"stats": {
"type": "object",
"properties": {
"inputBodyLen": {
"type": "integer",
"example": 2000
},
"rebootCount": {
"type": "integer",
"example": 0
},
"restartCount": {
"type": "integer",
"example": 0
},
"resurrectCount": {
"type": "integer",
"example": 0
},
"computeUnits": {
"type": "integer",
"example": 0
}
}
},
"options": {
"type": "object",
"properties": {
"build": {
"type": "string",
"example": "latest"
},
"timeoutSecs": {
"type": "integer",
"example": 300
},
"memoryMbytes": {
"type": "integer",
"example": 1024
},
"diskMbytes": {
"type": "integer",
"example": 2048
}
}
},
"buildId": {
"type": "string"
},
"defaultKeyValueStoreId": {
"type": "string"
},
"defaultDatasetId": {
"type": "string"
},
"defaultRequestQueueId": {
"type": "string"
},
"buildNumber": {
"type": "string",
"example": "1.0.0"
},
"containerUrl": {
"type": "string"
},
"usage": {
"type": "object",
"properties": {
"ACTOR_COMPUTE_UNITS": {
"type": "integer",
"example": 0
},
"DATASET_READS": {
"type": "integer",
"example": 0
},
"DATASET_WRITES": {
"type": "integer",
"example": 0
},
"KEY_VALUE_STORE_READS": {
"type": "integer",
"example": 0
},
"KEY_VALUE_STORE_WRITES": {
"type": "integer",
"example": 1
},
"KEY_VALUE_STORE_LISTS": {
"type": "integer",
"example": 0
},
"REQUEST_QUEUE_READS": {
"type": "integer",
"example": 0
},
"REQUEST_QUEUE_WRITES": {
"type": "integer",
"example": 0
},
"DATA_TRANSFER_INTERNAL_GBYTES": {
"type": "integer",
"example": 0
},
"DATA_TRANSFER_EXTERNAL_GBYTES": {
"type": "integer",
"example": 0
},
"PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
"type": "integer",
"example": 0
},
"PROXY_SERPS": {
"type": "integer",
"example": 0
}
}
},
"usageTotalUsd": {
"type": "number",
"example": 0.00005
},
"usageUsd": {
"type": "object",
"properties": {
"ACTOR_COMPUTE_UNITS": {
"type": "integer",
"example": 0
},
"DATASET_READS": {
"type": "integer",
"example": 0
},
"DATASET_WRITES": {
"type": "integer",
"example": 0
},
"KEY_VALUE_STORE_READS": {
"type": "integer",
"example": 0
},
"KEY_VALUE_STORE_WRITES": {
"type": "number",
"example": 0.00005
},
"KEY_VALUE_STORE_LISTS": {
"type": "integer",
"example": 0
},
"REQUEST_QUEUE_READS": {
"type": "integer",
"example": 0
},
"REQUEST_QUEUE_WRITES": {
"type": "integer",
"example": 0
},
"DATA_TRANSFER_INTERNAL_GBYTES": {
"type": "integer",
"example": 0
},
"DATA_TRANSFER_EXTERNAL_GBYTES": {
"type": "integer",
"example": 0
},
"PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
"type": "integer",
"example": 0
},
"PROXY_SERPS": {
"type": "integer",
"example": 0
}
}
}
}
}
}
}
}
}
}
```