# 京东 JD.com 关键词搜索 API (jd.search)

- Canonical page: [https://everyinfra.com/jd-api/search](https://everyinfra.com/jd-api/search?utm_medium=ai_doc&utm_campaign=page_md)
- Endpoint: POST https://api.everyinfra.com/api/v1/social with {"platform": "jd", "action": "search", "params": {...}}
- Price: $0.002472 per call ($2.47 per 1,000 requests); failed calls and empty results are not charged
- Billing unit: every 5 rows you ask for count as one call; blocks that come back with no rows are not charged
- Returns: list, default 5, max 30 per call
- Pagination: pass next_page_token back as page_token for the next page, other params unchanged; each page is billed by its row count, one call per 5 rows, tokens last 24 hours; up to 150 rows
- Mode: sync; add "mode": "async" for slow tasks

京东关键词搜索按 `keyword` 检索京东商品，返回商品 ID、标题与短标题、价格、评价条数、好评率、店铺、是否京东自营、促销标签和卖点。它回答「搜这个词，京东上排在前面的是哪些商品、谁在卖、口碑如何」，适合做选品初筛、价格带摸底，以及自营与第三方店铺的对比。

中文关键词通常更贴近站内商品标题，命中更准。结果里的 `item_id` 可以直接交给京东的商品详情、评价能力继续深挖；`good_rate` 是京东公开的好评率百分比，要和评价数一起看；`review_count`、`sold_count` 是列表上显示的文字（如「10万+」），不是精确数字。

## Health

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

## Parameters

| name | type | required | default | description |
|---|---|---|---|---|
| keyword | not declared | yes | not declared | 京东商品搜索词；中文关键词通常更贴近站内商品标题。 |
| page | integer | no | not declared | 搜索结果的页码，整数；不传或传 1 就是第 1 页。取值范围是 1 到 150 ÷ limit（向上取整）：limit 30 时 1–5，默认 limit 5 时 1–30，limit 10 时 1–15。用 page 时，每页条数就是这次请求的 limit（1–30）。每一页都按第 1 页的价收，只按这一页自己的条数分档，每 5 条算一次调用：limit 30 时每页 30 条算 6 次，limit 5 时每页算 1 次。用 page=N 直接跳到第 N 页，这一次按 N 页收，和一页页翻到第 N 页收得一样（前面 N − 1 页按整页算，加上第 N 页本身）：limit 30、page 5 一次算 30 次调用。第 N 页没返回的条数对应的档退回；第 N 页是空的（比如列表没那么长），整次不扣费。page 超出范围、是 0、负数、小数、字符串（如 "2"）或布尔值时，扣费前返回 422，不扣费。同步请求就能翻到最深那一页（第 150 条），不用加 "mode": "async"。最深那一页（limit 30 时是第 5 页）没有 next_page_token，pagination.stop_reason 为 depth_limit；列表本来就短、翻到头时为 end_of_list。第 1 页每次都现取。第 2 页起从一份保存下来的完整列表（最多 150 条）里按顺序切；第一次要第 2 页或更后面的页时，这份列表最多是一小时前的。用 page 直接要的页，从这份列表里按原位置切（第 N 页 = 列表里第 (N − 1) × limit + 1 条起的 limit 条）。它不知道你之前拿到的第 1 页是什么样，所以和单独取的第 1 页之间、或者跨了整点再要的页之间，可能有几件商品重复或缺漏，合并时按 item_id 去重。要一页不重复地读完整个列表，从第 1 页起跟着 next_page_token 翻。pagination.page 是这一页的页码；pagination.has_more 为 true 就还有下一页：接着传 page + 1，或把 next_page_token 作为 page_token 传回。page 和 page_token 同传时以 page_token 为准。按页码要到的页也会给 next_page_token，下一次带不带 page 都能用它。 |
| page_token | not declared | no | not declared | 翻页令牌。第 1 页不用传；响应里有 next_page_token 时，把它原样作为 page_token 传回就拿下一页，其余参数保持不变。每页条数沿用拿到这个令牌的那次请求的 limit，之后改 limit 不起作用。也可以不用令牌，用 page 直接要第 N 页；page 和 page_token 同传时以 page_token 为准。令牌 24 小时内有效，只能用于同一组参数、同一个账户；换了参数会被拒（422，不扣费）。每一页都按第 1 页的价收，只按这一页自己的条数分档，每 5 条算一次调用：limit 30 时每页 30 条算 6 次，翻到第 5 页一共 5 页、30 次调用；limit 5 时每页算 1 次。没返回的条数对应的档退回，一条都没返回的空页（比如翻过了短列表的末页）不扣费。最多翻到第 150 条（limit 30 时是 5 页），同步请求就能翻到，不用加 "mode": "async"。第 150 条所在的那一页没有 next_page_token，pagination.stop_reason 为 depth_limit；列表本来就短、翻到头时为 end_of_list。第 1 页每次都现取。第 2 页起从一份保存下来的完整列表（最多 150 条）里按顺序切；第一次要第 2 页或更后面的页时，这份列表最多是一小时前的。用 page_token 从第 1 页一路翻下去，后面每一页都从同一份列表里切：第 1 页已经给过的商品不再出现，中间也不漏，所以各页之间没有重复的商品。翻得慢也一样，这条令牌链一直用它第一次到第 2 页时的那一份。pagination.page 是这一页的页码；pagination.has_more 为 true 就还有下一页，把 next_page_token 作为 page_token 传回。按页码要到的页也会给 next_page_token，下一次带不带 page 都能用它。 |
| limit | integer (1–30) | no | 5 | 这次调用最多返回的条数，整数，1–30；不传按默认值，实际返回可能少于这个数。超过上限会在扣费前返回 422。 |

## Response fields (items in `results`)

| field | meaning |
|---|---|
| item_id | 京东商品数字 ID；search 可把它直接交给详情、评价或价格能力。 |
| url | 该记录在原平台上的可访问链接。 |
| title | 标题。平台无标题概念时（如纯文本帖）为 null。 |
| short_title | 京东返回的商品短标题。 |
| price | 价格数值，不含货币符号；币种见 currency。 |
| currency | 价格币种代码（如 CNY、USD）。price 存在但 currency 为 null 时不要假定币种。 |
| sold_count | 搜索列表上显示的销量原文（search），是「10万+」这类文本、不是精确件数；可能缺省。 |
| review_count | 搜索列表上显示的评价数原文（search），是文本、可能是约数，不是精确条数。 |
| good_rate | 京东公开的好评率百分比。 |
| shop_id | 京东店铺数字 ID。 |
| shop_name | 公开店铺名称。 |
| shop_url | 京东店铺公开页面。 |
| is_jd_self | 是否为京东自营商品。 |
| promotion | 商品列表中的促销标签。 |
| sell_point | 商品列表中的公开卖点。 |
| category_ids | 京东类目 ID 路径。 |
| image_url | 图片链接：search、product_detail、shop、skus 里是商品主图（封面）；description_images 里是这一行的那张详情图（京东图床的 https 原图）。 |
| 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": "jd",
  "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": "jd",
        "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-24T18:28:34Z. `results` and `count` are real with personal information (names, handles, avatars, profile links, contact details) removed; the list keeps the first 2 of 5. `id`, `billing` and `quota` differ on every call, so only their shape is shown.

```text
{
  "id": "req_…",
  "platform": "jd",
  "action": "search",
  "results": [
    {
      "item_id": "10237497167004",
      "url": "https://item.jd.com/10237497167004.html",
      "title": "华为手机2026热销新机上市畅享 90 Plus 麒麟8系芯片丝滑超好用鸿蒙AI防诈6620mAh巨鲸大电池柔光护眼 星空黑【128GB】 官方标配【365天延保+蓝牙耳机+运费险】",
      "price": 1999,
      "currency": "CNY",
      "shop_id": "219104371",
      "shop_name": "迪旺手机专营店",
      "shop_url": "https://mall.jd.com/index-219104371.html",
      "category_ids": [
        "9987",
        "653",
        "655"
      ],
      "image_url": "https://img14.360buyimg.com/n0/jfs/t1/547105/14/3627/77818/6ad1919eFd3fb2338/0083320320125c52.png",
      "platform": "jd"
    },
    {
      "item_id": "10230554159591",
      "url": "https://item.jd.com/10230554159591.html",
      "title": "华为mate60pro手机智能手机鸿蒙智能AI手机麒麟芯片正品国行mate60赠手机壳 Mate60Pro【雅川青】 12GB+256GB 7天试用（送手机壳88W充电器）",
      "price": 2837,
      "currency": "CNY",
      "shop_id": "169276555",
      "shop_name": "尊享数码手机拼购店",
      "shop_url": "https://mall.jd.com/index-169276555.html",
      "category_ids": [
        "9987",
        "653",
        "655"
      ],
      "image_url": "https://img14.360buyimg.com/n0/jfs/t1/483100/15/10357/93091/6a647f40Ff1f84472/008332032085260d.jpg",
      "platform": "jd"
    }
  ],
  "next_page_token": …,
  "pagination": { … },
  "count": 5,
  "billing": {
    "charged": …,
    "charged_usd": …,
    "balance_after_usd": …,
    …
  },
  "quota": { … }
}
```

## FAQ

### 用英文关键词能搜吗？

能，但中文关键词通常更贴近京东站内的商品标题，命中更准。搜品牌加型号时，按商品标题里常见的写法填写，效果更好。

### 搜索结果怎么继续查详情和评价？

每条结果的 `item_id` 是京东商品数字 ID，直接传给京东的商品详情、评价或价格能力即可，不需要再拼商品链接。

### 怎么区分京东自营和第三方店铺？

看 `is_jd_self`，为真表示京东自营商品；店铺信息在 `shop_name`、`shop_id` 和 `shop_url`。比较价格和口碑时，把自营和第三方分开看更公平。

## Also

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