# 1688 Search API (alibaba1688.search)

- Canonical page: https://everyinfra.com/en/alibaba1688-api/search
- Endpoint: POST https://api.everyinfra.com/api/v1/social with {"platform": "alibaba1688", "action": "search", "params": {...}}
- Price: $0.002778 per call ($2.78 per 1,000 requests); failed calls and empty results are not charged
- Returns: list, default 20, max 100 per call
- Mode: sync; add "mode": "async" for slow tasks

1688 Search finds wholesale products by `keyword` and returns each one's title, price range, minimum order quantity, units sold, repurchase rate, supplier name, location, business type and years on the platform, stock status and whether it supports dropshipping. Use it to see which suppliers carry a product and roughly what ordering terms and prices look like: the first step in sourcing, comparing suppliers or picking products for a dropshipping store.

Bound the price with `min_price` and `max_price`, filter by city with `city`, and order with `sort` (relevance, best-selling, or price up or down). Read `min_order_quantity` first, since it is the first threshold in wholesale buying; `repurchase_rate` and `supplier_composite_score` let you screen suppliers before opening any product. Price filters do not guarantee that every variant and quantity tier falls in range; the tiered prices in product details are what count.

## Health

- Live health (24h percent, hourly and daily trends): https://api.everyinfra.com/api/v1/social/availability?platform=alibaba1688&action=search

## Parameters

| name | type | required | default | description |
|---|---|---|---|---|
| keyword | not declared | yes | not declared | Specifies the search term for 1688 wholesale products (for example, insulated mugs or cardboard boxes). Use product terms rather than store names or offerIds; minimum order quantities and tier pricing return inside item details. |
| city | not declared | no | not declared | Filters 1688 wholesale item queries by city name text. This filter does not reflect account locations, change returned seller addresses, or guarantee persistent filtering on single-product detail requests. |
| max_price | not declared | no | not declared | Filters wholesale items by maximum unit price as a numeric value. Decimals are allowed; when a call falls back to whole-yuan filtering they round up (145.98 becomes 146), so the range only widens. It operates alongside min_price to bound price ranges rather than tier order quantities, and it may not cover every SKU variant or volume discount tier. |
| min_price | not declared | no | not declared | Filters wholesale items by minimum unit price as a numeric value. Decimals are allowed; when a call falls back to whole-yuan filtering they round down (39.81 becomes 39), so the range only widens. This parameter sets item criteria rather than minimum order quantities or API spend limits, and returned tier pricing varies by order volume. |
| sort | enum: popular / price_asc / price_desc / relevance | no | not declared | Sorts search items by relevance (default for search), popular, price_asc, or price_desc. Sorting criteria do not guarantee exact sales figures or total transaction amounts in the payload. |
| limit | integer (1–100) | no | 20 | The most rows to return in this call, an integer from 1 to 100. The default applies when you leave it out, and a call can return fewer rows. Larger values return 422 before any charge. |

## Response fields (items in `results`)

| field | meaning |
|---|---|
| id | The record's unique ID on the platform. Unique only within one platform; IDs can repeat across platforms. |
| url | Link to the record on the platform. |
| title | Title. null when the platform has no titles (for example text-only posts). |
| text | Body text with HTML removed, returned in full and never cut short (on a few platforms the list results themselves carry only an excerpt; the platform's field notes say so). |
| price_min | Lower bound of the price range. |
| price_max | Upper bound of the price range. |
| currency | Currency code of the price (for example CNY, USD). If price is present but currency is null, do not assume a currency. |
| min_order_quantity | Minimum order quantity (MOQ). **The first threshold in 1688 wholesale buying: check it before anything else.** |
| order_count | Order count. |
| repurchase_rate | Repurchase rate. **One of the firmest signals of supplier quality on 1688.** |
| category | Category name in the platform's own taxonomy, not normalized across platforms. In product details it may be empty on a sync call; an async call usually returns it. |
| city | City name in the platform's language, not normalized. In product details it may be empty on a sync call; an async call usually returns it. |
| province | Province where the supplier is based. In product details it may be empty on a sync call; an async call usually returns it. |
| supplier_name | Supplier name. |
| is_out_of_stock | Whether the product is out of stock. In product details it may be empty on a sync call; an async call usually returns it. |
| supports_dropship | Whether the supplier ships single units on your behalf (dropshipping). A key filter for selling without holding stock. In product details it may be empty on a sync call; an async call usually returns it. |
| images | Main product image links in page order; in product_detail some listings also include variant (SKU) images, and description-area images are in description_images. Absent when there are no images. |
| supplier_type | Supplier business mode (e.g. manufacturer, wholesaler). In product details it may be empty on a sync call; an async call usually returns it. |
| supplier_years | Years the supplier has been on the 1688 platform. In product details it may be empty on a sync call; an async call usually returns it. |
| supplier_shop_url | Supplier shop link. |
| supplier_composite_score | Supplier composite service score (1-5). |
| sold_count_text | Sales as originally displayed on search rows (Chinese source text, e.g. 100+ sold network-wide). |
| service_tags | Service label list on search rows. |
| product_badges | Product badge list on search rows (e.g. 7×24H response). |
| rating | Overall product rating (1-5). In product details it may be empty on a sync call; an async call usually returns it. |
| rating_scale | Maximum of rating in the same row: 5 for five-star scales, 10 for ten-point scales. Present only when the row has a rating. In product details it may be empty on a sync call; an async call usually returns it. |
| review_count | Total review count. In product details it may be empty on a sync call; an async call usually returns it. |
| positive_rate | Positive-review rate as a 0-1 fraction (0.999 = 99.9%). In product details it may be empty on a sync call; an async call usually returns it. |
| sold_count | Units sold. |
| sold_display | Sales as originally displayed (Chinese source text, e.g. 100k+ sold); for the numeric figure use sold_count. In product details it may be empty on a sync call; an async call usually returns it. |
| want_buy_count | Number of buyers who marked the listing as wanted (a sourcing-demand signal). In product details it may be empty on a sync call; an async call usually returns it. |
| stock | Stock. In product details it may be empty on a sync call; an async call usually returns it. |
| unit | Pricing unit (piece, item, carton and so on). |
| category_path | Full category path with Chinese segment names (e.g. Digital > Phone accessories > Phone case, in the source language). In product details it may be empty on a sync call; an async call usually returns it. |
| video_url | Product video URL, when the listing has one. |
| winport_url | Supplier's 1688 storefront link. |
| supplier_fans | Supplier follower count. In product details it may be empty on a sync call; an async call usually returns it. |
| supplier_founded_year | Year the supplier was founded. |
| price_tiers | Tiered prices: the unit price falls as the order quantity rises. Read each tier with its minimum quantity. |
| specs | Product specification table: list of {name, value} pairs (e.g. Material: TPU). In product details it may be empty on a sync call; an async call usually returns it. |
| description_images | Detail-description image URL list, in the listing's original order; null when the listing has none. In product details it may be empty on a sync call; an async call usually returns it. |
| coupons | platform-native meaning |
| promotion_details | platform-native meaning |
| service_details | Service guarantee details: code (service code), name, description (the rule), rule_url (rule page). services / service_tags give names only. In product details it may be empty on a sync call; an async call usually returns it. |
| purchase_limits | platform-native meaning |
| mix_wholesale | platform-native meaning |
| supports_mix | Whether the listing accepts mixed orders (combining different styles to meet the minimum order quantity). In product details it may be empty on a sync call; an async call usually returns it. |
| review_tags | Buyer impression tags: [{tag, count}], for example “soft fabric” ×2. In product details it may be empty on a sync call; an async call usually returns it. |
| refund_rate | platform-native meaning |
| review_negative_count | platform-native meaning |
| review_neutral_count | platform-native meaning |
| review_with_photo_count | Number of reviews with photos; null means not provided, not 0. In product details it may be empty on a sync call; an async call usually returns it. |
| review_with_text_count | Number of reviews with text; null means not provided, not 0. In product details it may be empty on a sync call; an async call usually returns it. |
| supplier_stats | Supplier profile (only keys with values): employee_count, plant_area_sqm (factory area in m²), plant_type (for example, own factory), equipment_count (main equipment), product_count (products on sale), repeat_rate (repeat-buyer rate, 0-1), repeat_buyer_count_text / cross_border_buyer_count_text (repeat and cross-border buyers as shown, such as 300+), response_rate (0-1), positive_review_rate (0-1), fulfillment_rate (0-1), certificate_count / certificates / management_certificates (certificate count, names and management-system certifications), patent_count, oem_mode (OEM/ODM), own_brands (own brands as shown), brand_count, partner_brand, is_major_brand_partner (supplies major brands), scale_tier (size tier), honors. In product details it may be empty on a sync call; an async call usually returns it. |
| supplier_scores | platform-native meaning |
| supplier_metric_tags | platform-native meaning |
| supplier_rank | platform-native meaning |
| supplier_industry_belt | Industrial-cluster certification: description (for example, a 1688-certified flagship merchant of a regional apparel cluster), link_url (certification page). In product details it may be empty on a sync call; an async call usually returns it. |
| supplier_certification | Third-party factory or business audit: agency (auditor code, such as sgs or tuv), report_number (report number as shown), report_url (report page). In product details it may be empty on a sync call; an async call usually returns it. |
| supplier_verification_tags | platform-native meaning |
| supplier_inspection_report_url | platform-native meaning |
| supplier_videos | platform-native meaning |
| supplier_address | Supplier address as shown. In product details it may be empty on a sync call; an async call usually returns it. |
| supplier_coordinates | Supplier location: {longitude, latitude}. In product details it may be empty on a sync call; an async call usually returns it. |
| supplier_main_category | Supplier's main category. In product details it may be empty on a sync call; an async call usually returns it. |
| customization | platform-native meaning |
| shipping | platform-native meaning |
| unit_weight_kg | Weight of one unit, in kilograms. In product details it may be empty on a sync call; an async call usually returns it. |
| platform | Source platform identifier, the same as platform in the request (for example xiaohongshu, tiktok). |

## Example

```bash
curl -X POST 'https://api.everyinfra.com/api/v1/social' \
  -H "Authorization: Bearer $EVERYINFRA_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "platform": "alibaba1688",
  "action": "search",
  "params": {
    "keyword": "不锈钢保温杯"
  }
}'
```

```python
import os
import requests

response = requests.post(
    "https://api.everyinfra.com/api/v1/social",
    headers={"Authorization": f"Bearer {os.environ['EVERYINFRA_API_KEY']}"},
    json={
        "platform": "alibaba1688",
        "action": "search",
        "params": {
            "keyword": "不锈钢保温杯",
        },
    },
    timeout=120,
)
print(response.status_code)
print(response.json())
```

## Response example

Real response to the example request above, captured 2026-10-13T04:57:06Z. `results` and `count` are real with personal information (names, handles, avatars, profile links, contact details) removed; the list keeps the first 2 of 20. `id`, `billing` and `quota` differ on every call, so only their shape is shown.

```text
{
  "id": "req_…",
  "platform": "alibaba1688",
  "action": "search",
  "results": [
    {
      "id": "•••",
      "url": "https://detail.1688.com/offer/901095512547.html",
      "title": "跨境美式太空壶304不锈钢双层真空保温杯大容量运动水壶登山水壶",
      "price_min": 12.5,
      "currency": "CNY",
      "order_count": 33,
      "repurchase_rate": 20,
      "city": "永康市",
      "province": "浙江",
      "supplier_name": "永康市钛霖杯业有限公司",
      "images": [
        "https://cbu01.alicdn.com/img/ibank/O1CN01LbpPbm2B0StIPXCWn_!!2219521848276-0-cib.jpg"
      ],
      "supplier_type": "生产加工",
      "supplier_years": 2,
      "supplier_shop_url": "https://shop81l5635to8463.1688.com",
      "sold_count_text": "已售1200+件",
      "service_tags": [
        "退货包运费",
        "先采后付",
        "回头率54%"
      ],
      "product_badges": [
        "先采后付"
      ],
      "platform": "1688"
    },
    {
      "id": "•••",
      "url": "https://detail.1688.com/offer/1080785307425.html",
      "title": "新款彩色304不锈钢保温杯 便携手提弹跳盖户外便携运动水杯定 制",
      "price_min": 24,
      "currency": "CNY",
      "min_order_quantity": 1,
      "order_count": 49,
      "repurchase_rate": 14,
      "city": "金华市",
      "province": "浙江",
      "supplier_name": "永康市大表哥工贸有限公司",
      "images": [
        "https://cbu01.alicdn.com/img/ibank/O1CN01NbBs3QLcV7L3thOC_!!2217763939489-0-cib.jpg"
      ],
      "supplier_type": "生产加工",
      "supplier_years": 3,
      "supplier_shop_url": "https://15727971454.1688.com",
      "sold_count_text": "已售500+件",
      "service_tags": [
        "退货包运费",
        "先采后付",
        "回头率67%"
      ],
      "product_badges": [
        "7×24H响应",
        "先采后付"
      ],
      "platform": "1688"
    }
  ],
  "count": 20,
  "billing": {
    "charged": …,
    "charged_usd": …,
    "balance_after_usd": …,
    …
  },
  "quota": { … }
}
```

## FAQ

### Why don't filtered prices match the product page?

1688 prices are tiered: the unit price depends on how many you buy. `min_price` and `max_price` filter on the price shown in search, without guaranteeing that every variant or quantity tier falls in range. The tiered prices in product details are the actual quote.

### What does `city` filter on?

It filters products by city text. It is not your account's location and does not change the supplier addresses returned; read where goods ship from in each result's `city` and `province`.

### How do I find suppliers that dropship?

Keep results where `supports_dropship` is true, then check `min_order_quantity` and `is_out_of_stock` to see whether you can order small quantities and whether the item is in stock. A high `repurchase_rate` and a long `supplier_years` are useful signs the supplier delivers consistently.

## Also

- Capability catalog (no key): https://api.everyinfra.com/api/v1/social/catalog?platform=alibaba1688
- OpenAPI: https://everyinfra.com/openapi.json · Agents guide: https://everyinfra.com/agents.md
