# Shopee 关键词搜索 API (shopee.search)

- Canonical page: [https://everyinfra.com/shopee-api/search](https://everyinfra.com/shopee-api/search?utm_medium=ai_doc&utm_campaign=page_md)
- Endpoint: POST https://api.everyinfra.com/api/v1/social with {"platform": "shopee", "action": "search", "params": {...}}
- Price: $0.006403 per call ($6.4 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

关键词搜索按 `keyword` 在一个 Shopee 站点里找商品，每行带店铺 ID、商品 ID、名称、`price` 和 `currency`、`original_price`、折扣 `discount_pct`、评分、销量 `sold_count`，以及 `is_mall`，标明是不是 Shopee Mall 官方店。它回答「这个词在这个站点上有哪些商品、价位和销量怎样」，适合选品调研、竞品比价和找热销款。

搜哪个站点由 `country` 决定，不传默认 `id`（印度尼西亚）。`min_price`、`max_price` 按该站点的币种填写，带小数会被取整，不要把同一个数拿去另一个站点用。`sort` 取 `popular` 是销量相关排序，取 `price_asc` 是价格升序。

## Health

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

## Parameters

| name | type | required | default | description |
|---|---|---|---|---|
| keyword | not declared | yes | not declared | 商品关键词；搜索哪个地区商城由 country 决定。 |
| country | enum: br / cl / co / id / mx / my / ph / sg / th / tw / vn | no | not declared | 商城地区代码，支持 id/sg/my/th/ph/vn/br/tw/mx/co/cl，未指定时默认 id（印度尼西亚）。这是商城选择，不保证每个地区都有结果。 |
| max_price | not declared | no | not declared | 最高商品价格，按目标商城使用的币种填写；与 min_price 配合使用。按整数筛选，带小数时向上取整。 |
| min_price | not declared | no | not declared | 最低商品价格，按目标商城使用的币种填写；不要跨地区把数值当成同一币种，也不是 API 计费金额。按整数筛选，带小数时向下取整。 |
| sort | enum: newest / popular / price_asc / price_desc / relevance | no | not declared | 商品排序：relevance 相关性、popular 销量相关排序、newest 最新、price_asc 价格升序、price_desc 价格降序。 |
| limit | integer (1–100) | no | 20 | 这次调用最多返回的条数，整数，1–100；不传按默认值，实际返回可能少于这个数。超过上限会在扣费前返回 422。 |

## Response fields (items in `results`)

| field | meaning |
|---|---|
| shop_id | 店铺 ID。 |
| item_id | 商品 ID。 |
| name | 名称。用于账号/商品/商家类能力，指该对象本身的名字。 |
| url | 该记录在原平台上的可访问链接。 |
| image_url | 图片链接。多图能力可能返回 image_urls 数组。 |
| price | 价格数值，不含货币符号；币种见 currency。商品详情（product_detail）缺价格时这次调用不扣费，其余数据照常返回。 |
| original_price | 原价。 |
| discount_pct | 折扣百分比。 |
| currency | 价格币种代码（如 CNY、USD）。price 存在但 currency 为 null 时不要假定币种。 |
| rating | 评分。**分制随平台而异**，同一行的 `rating_scale` 给出该平台满分 (多数是 5，Booking/豆瓣/爱奇艺/NAVER 是 10)。跨平台比较前必须先按 rating_scale 换算。直接比数字会得出反的结论。 |
| rating_scale | 上一列 `rating` 的满分。5 表示五星制、10 表示十分制。只在该行有 rating 时出现。 |
| rating_count | 参与评分的人数。null 表示不公开，不等于 0。 |
| sold_count | 销量。 |
| location | 地理位置描述，原文透传，格式随平台而异。 |
| is_mall | 是否为 Shopee Mall 官方店。**东南亚电商里辨真假货的第一信号**。 |
| platform | 数据来源平台标识，与请求里的 platform 一致（如 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": "shopee",
  "action": "search",
  "params": {
    "keyword": "wireless mouse"
  }
}'
```

```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": "shopee",
        "action": "search",
        "params": {
            "keyword": "wireless mouse",
        },
    },
    timeout=120,
)
print(response.status_code)
print(response.json())
```

## Response example

Real response to the example request above, captured 2026-09-26T08:56:04Z. `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": "shopee",
  "action": "search",
  "results": [
    {
      "shop_id": 487136590,
      "item_id": 23911735997,
      "name": "MOFii Mouse Wireless Gaming Rechargeable Baterai Type-C Fast Charging 1600DPI RGB Light P6",
      "url": "https://shopee.co.id/MOFii-Mouse-Wireless-Gaming-Rechargeable-Baterai-Type-C-Fast-Charging-1600DPI-RGB-Light-P6-i.487136590.23911735997",
      "image_url": "https://down-id.img.susercontent.com/file/id-11134207-7qul0-li9nrexr1rvb70",
      "price": 80000,
      "original_price": 299900,
      "currency": "IDR",
      "rating": 4.9,
      "location": "Tangerang",
      "is_mall": false,
      "platform": "shopee",
      "rating_scale": 5
    },
    {
      "shop_id": 992148841,
      "item_id": 25190075617,
      "name": "[COD] Mouse Bluetooth Dual-Mode Wireless 2.4G Silent Mouse USB Portable Charging Gaming Mouse For IPad Windows los",
      "url": "https://shopee.co.id/-COD-Mouse-Bluetooth-Dual-Mode-Wireless-2.4G-Silent-Mouse-USB-Portable-Charging-Gaming-Mouse-For-IPad-Windows-los-i.992148841.25190075617",
      "image_url": "https://down-id.img.susercontent.com/file/id-11134207-7rbke-m8vjok4qdvcr7f",
      "price": 30900,
      "original_price": 58000,
      "currency": "IDR",
      "rating": 4.9,
      "location": "Jakarta Barat",
      "is_mall": false,
      "platform": "shopee",
      "rating_scale": 5
    }
  ],
  "count": 20,
  "billing": {
    "charged": …,
    "charged_usd": …,
    "balance_after_usd": …,
    …
  },
  "quota": { … }
}
```

## FAQ

### `min_price` 和 `max_price` 怎么填才对？

按目标站点使用的币种填整数，带小数时 `min_price` 向下取整，`max_price` 向上取整。两个参数配合使用，圈出价格区间。不同站点的币种不同，同一个数字换站点就是另一个价位，所以不要跨站点复用。

### `country` 传了为什么搜不到结果？

`country` 只是选站点，不保证每个站点都有结果；支持的取值有 `id`、`sg`、`my`、`th`、`ph`、`vn`、`br`、`tw`、`mx`、`co`、`cl`，不传时默认 `id`。某个站点搜不到，不代表词本身没有商品。

### 什么时候用搜索，什么时候用店铺资料？

还没有目标店铺、按词找商品，用这一页。已经知道要看哪家店、想列出它店内的商品，用店铺资料，传店铺用户名或数字 shop ID。结果里 `is_mall` 为真是 Shopee Mall 官方店，在东南亚电商里，这是辨别真假货的第一信号。

## Also

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