# 1688 Image Search API: Photo to Factory Matches and Prices (`tenfoldfleet/1688-image-search-suppliers-by-photo`) Actor

Search 1688 by image to find the factory or supplier of a product: send photo URLs, receive the similar 1688.com offers in rank order with CNY price, minimum order, sold count, supplier type, region and years. $4 per 1,000 photos + $0.40 per 1,000 matches. Ads and failed photos free.

- **URL**: https://apify.com/tenfoldfleet/1688-image-search-suppliers-by-photo.md
- **Developed by:** [Tenfold Fleet](https://apify.com/tenfoldfleet) (community)
- **Categories:** E-commerce, Agents, MCP servers
- **Features:** Limited permissions
- **Stats:** 1 total users, 0 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $4.00 / 1,000 image searches

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

### What does 1688 Image Search API do?

**1688 Image Search API** turns a product photo into a ranked list of **1688.com** offers that look like it. 1688 is Alibaba Group's wholesale marketplace for buyers inside China, and it is where a large share of factories post their lowest quotes. Send image URLs taken from Amazon, Shopify, Temu, AliExpress or your own shop. Each match comes back as one row with the **wholesale price in CNY, minimum order, units sold** and the **supplier that posted it**: company name, seller type, province and city, years on 1688, inspection badges, repeat-buyer rate and service score.

It is a **1688 search by image API** that works without an account, a cookie or a phone check. Requests go over plain HTTP without a browser, several photos run at once, and one photo can return as many as 600 organic listings. The price is **$0.004 per photo plus $0.40 per 1,000 matches**. Sponsored listings, photos without a match and photos that fail cost nothing.

Not affiliated with 1688.com or Alibaba Group. How you use the data is your responsibility: follow 1688's terms and your local law.

### Why use it?

- 🏭 **Trace a product to its maker**: a competitor's listing photo becomes a list of 1688 sellers offering that item, each with its wholesale price.
- 💰 **Work out the margin before ordering**: put the 1688 price next to the retail price on Amazon, Shopify or AliExpress.
- 🔎 **Shortlist suppliers quickly**: rows carry the seller type (manufacturer or wholesaler, when 1688 states it), the years on 1688 and the share of buyers who reorder.
- 🚫 **Sponsored listings kept out**: a share of every 1688 image results page is paid placement, often a fifth of the page or more. Those rows are dropped by default and never billed.
- 🤖 **Ready for agents and pipelines**: flat JSON, the same keys in every row, and one free error row for each photo that could not be searched.

#### How is it different from other 1688 image search Actors?

- **Depth**: as many as 600 organic listings for one photo, where a fixed top 20 is common.
- **No base fee per run** beyond Apify's $0.00005 start event, so one photo costs the same alone as in a batch of 1,000.
- **You pay for organic matches only**. Sponsored rows are free when you ask for them, and a photo that returns nothing but sponsored rows is free too.
- **Supplier checks inside the match row**: seller type, inspection badges, reorder rate and service score arrive without a second request per product.
- **Shortcut for 1688 pictures**: an image that already sits on `cbu01.alicdn.com` is searched by its address, with no upload step.
- **Safe to interrupt**: a run that Apify restarts, or that you resurrect, continues where it stopped and bills no photo or match twice.

### What data can it extract?

| Field | Description |
|---|---|
| `inputImage` | The photo URL you sent |
| `offerId`, `offerUrl` | 1688 listing ID and link |
| `title` | Listing title (Chinese) |
| `price`, `currency` | Entry price on the listing card, in CNY |
| `minOrderQuantity` | Minimum order |
| `soldCount`, `salesText`, `bookedCount` | Units sold (number and 1688's own text) and order count |
| `matchScore` | Raw similarity number from 1688. Its scale changes from photo to photo and it does not follow the rank, so use `position` for order |
| `companyName`, `supplierLoginId`, `memberId`, `shopUrl` | Supplier |
| `businessType` | `manufacturer`, `wholesaler`, `agent` or `service`; `null` when 1688 does not state it (about a quarter of rows) |
| `supplierProvince`, `supplierCity`, `yearsOnPlatform` | Supplier location and years on 1688 |
| `factoryInspection`, `businessInspection`, `superFactory` | 1688 audit badges |
| `repurchaseRate`, `tradeServiceScores`, `serviceTags` | Reorder rate, service score, service labels |
| `imageUrl` | Listing photo |
| `isAd` | `true` on a sponsored row (these appear only with "Include paid ads") |
| `position`, `page`, `totalFound` | Rank on 1688, results page, and the match count 1688 reports |
| `details` | Optional product page data: price tiers, stock, specifications, photos, video, ship-from city, unit weight |

### How to search 1688 by image

1. Put your product photo URLs into **Product photo URLs**, one per line.
2. Choose **Max matches per photo**: 60 is the default and 600 the ceiling.
3. If you need quantity price tiers, stock and specifications for the top matches, turn on **Open product pages**.
4. Press **Start**. Expect roughly 10 to 20 seconds per photo for the first 60 matches; five photos run side by side by default.
5. Export the dataset to JSON, CSV or Excel, or pull it through the Apify API.

### How much does it cost?

| Event | Price |
|---|---|
| Image search (a photo with at least one organic match) | $0.004 |
| Matched product | $0.0004 ($0.40 per 1,000) |
| Product page (optional) | $0.003 |
| Actor start | $0.00005 |

Examples: 1 photo with 60 matches is **$0.028**; 100 photos with 20 matches each are **$1.20**. Residential proxy traffic is part of the price. Sponsored rows, duplicates, photos without a match and failed photos are free. Free plan: Apify's $5 of monthly credit pays for roughly 175 photos at 60 matches each.

### Input

```json
{
    "imageUrls": [
        "https://cbu01.alicdn.com/img/ibank/O1CN01nQ841G2GNtAvVu4sV_!!2216498669004-0-cib.jpg",
        "https://upload.wikimedia.org/wikipedia/commons/f/f4/Stainless_steel_water_bottle.jpg"
    ],
    "maxResultsPerImage": 60,
    "includeAds": false,
    "includeProductDetails": false
}
```

Accepted formats: JPG, PNG, WebP, GIF and AVIF. Size limit: 10 MB and 50 megapixels per file. The Actor shrinks every file to 500 px before it goes to 1688. One run takes up to 1,000 photos.

### Output

One row per match. Export the dataset to JSON, CSV, Excel or HTML.

```json
{
    "inputImage": "https://upload.wikimedia.org/wikipedia/commons/f/f4/Stainless_steel_water_bottle.jpg",
    "offerId": "978730088039",
    "title": "马卡龙色弹跳盖保温杯304不锈钢便携水杯学生户外随手杯礼品定制",
    "price": 21,
    "currency": "CNY",
    "minOrderQuantity": 1,
    "salesText": "400+件",
    "soldCount": 493,
    "bookedCount": 141,
    "matchScore": 0.74374,
    "supplierLoginId": "永康市沃胜工贸",
    "memberId": "b2b-22150854696560a16e",
    "companyName": "永康市沃胜工贸有限公司",
    "shopUrl": "https://664379010.1688.com",
    "businessType": "manufacturer",
    "businessTypeCn": "生产加工",
    "supplierProvince": "浙江",
    "supplierCity": "金华市",
    "yearsOnPlatform": 4,
    "factoryInspection": false,
    "businessInspection": false,
    "superFactory": false,
    "repurchaseRate": "65%",
    "tradeServiceScores": { "overall": 4.5 },
    "serviceTags": ["先采后付", "7天无理由"],
    "imageUrl": "https://cbu01.alicdn.com/O1CN01G990iK2LCVVCfIzP7_!!2215085469656-0-cib.jpg",
    "isAd": false,
    "offerUrl": "https://detail.1688.com/offer/978730088039.html",
    "position": 2,
    "page": 1,
    "totalFound": 700,
    "scrapedAt": "2026-11-10T00:33:04.787Z"
}
```

When a photo cannot be searched, the dataset gets a single free row holding `inputImage` and `error`.

### Tips

- A product shot alone against a plain backdrop gives the tightest matches. With a lifestyle photo, 1688 tends to match the scene.
- 1688 decides on its own which item in the frame to match. When it locks onto the wrong one, crop tighter and run again.
- Rows arrive in 1688's rank order (`position`). Filter on `businessType: "manufacturer"` and `factoryInspection` to bring factories to the front.
- `price` is the entry price in yuan from the listing card. Turn on **Open product pages** for the full quantity tiers.
- Cap your spend with the run option **Maximum cost per run**. The Actor stops at the cap and bills nothing past it.

### FAQ

#### Is a 1688 login required?

No login, cookie or phone verification. 1688 lets logged-out visitors search by picture, and the Actor works the same way.

#### Which photos work best?

Catalog photos from Amazon, Shopify, Temu, AliExpress, Alibaba or 1688 itself. Portraits, text-heavy screenshots and SVG files give poor or no matches.

#### Why did a photo return an error row?

Four causes cover nearly all cases: the URL did not serve an image, the file was over 10 MB, 1688 rejected the picture, or 1688 blocked the search on four fresh connections in a row. Error rows are free, so sending the photo again costs nothing.

#### Are the titles translated?

Not yet. Titles, company names and specifications come back in Chinese, as written on 1688.

#### What happens when a run is interrupted?

The Actor saves its progress after every page of matches. After a restart by Apify, or when you resurrect a run that timed out or was aborted, it skips finished photos and the matches it already delivered instead of charging them again.

#### Can I use this data legally?

The rows are business listings that 1688 displays to visitors without an account, and the Actor gathers no personal data. Whether your use is allowed depends on 1688's terms and on the law where you operate, so check both.

# Actor input Schema

## `imageUrls` (type: `array`):

Web addresses of the product pictures to look up, one per line. Any public picture works: a listing photo from Amazon, Shopify, Temu, AliExpress or 1688, or a file on your own server. Formats: JPG, PNG, WebP, GIF, AVIF; limit 10 MB per file and 1,000 photos per run. A product shown alone gives the best matches. A photo that fails or has no match is free.

## `maxResultsPerImage` (type: `integer`):

Upper limit of 1688 listings delivered per photo, in 1688's rank order (1688 holds about 700 per photo). Price: $0.004 for a photo that has a match, then $0.0004 per match, so 60 matches of one photo are $0.028. Free plan: Apify's $5 of monthly credit pays for roughly 175 photos at 60 matches each.

## `includeAds` (type: `boolean`):

A share of every 1688 image results page is sponsored. Those listings are dropped unless you switch this on. When on, they are delivered with isAd: true, cost nothing and are not counted in the max.

## `includeProductDetails` (type: `boolean`):

Read the 1688 product page of the top matches and attach a details object: quantity price tiers, minimum order, stock, specifications, the full photo set, video, ship-from city and unit weight. $0.003 per page that is read; a page that cannot be read is free.

## `maxDetailsPerImage` (type: `integer`):

Used with "Open product pages": the number of top matches per photo whose product page is read.

## `maxConcurrency` (type: `integer`):

Number of photos handled at the same time.

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

Leave as is. Searches go through Apify residential proxy, which is already paid by the event prices, because 1688 turns away datacenter addresses. Your own proxy URLs are accepted as an alternative.

## Actor input object example

```json
{
  "imageUrls": [
    "https://cbu01.alicdn.com/img/ibank/O1CN01nQ841G2GNtAvVu4sV_!!2216498669004-0-cib.jpg",
    "https://upload.wikimedia.org/wikipedia/commons/f/f4/Stainless_steel_water_bottle.jpg"
  ],
  "maxResultsPerImage": 60,
  "includeAds": false,
  "includeProductDetails": false,
  "maxDetailsPerImage": 10,
  "maxConcurrency": 5,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ]
  }
}
```

# 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 = {
    "imageUrls": [
        "https://cbu01.alicdn.com/img/ibank/O1CN01nQ841G2GNtAvVu4sV_!!2216498669004-0-cib.jpg",
        "https://upload.wikimedia.org/wikipedia/commons/f/f4/Stainless_steel_water_bottle.jpg"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("tenfoldfleet/1688-image-search-suppliers-by-photo").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 = { "imageUrls": [
        "https://cbu01.alicdn.com/img/ibank/O1CN01nQ841G2GNtAvVu4sV_!!2216498669004-0-cib.jpg",
        "https://upload.wikimedia.org/wikipedia/commons/f/f4/Stainless_steel_water_bottle.jpg",
    ] }

# Run the Actor and wait for it to finish
run = client.actor("tenfoldfleet/1688-image-search-suppliers-by-photo").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 '{
  "imageUrls": [
    "https://cbu01.alicdn.com/img/ibank/O1CN01nQ841G2GNtAvVu4sV_!!2216498669004-0-cib.jpg",
    "https://upload.wikimedia.org/wikipedia/commons/f/f4/Stainless_steel_water_bottle.jpg"
  ]
}' |
apify call tenfoldfleet/1688-image-search-suppliers-by-photo --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,tenfoldfleet/1688-image-search-suppliers-by-photo"
        }
    }
}
```

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/yuomGMlK1xVIH6lAp/builds/NklXuSGJG9d68syg9/openapi.json