# 京东 JD.com 店铺资料 API (jd.shop)

- Canonical page: [https://everyinfra.com/jd-api/shop](https://everyinfra.com/jd-api/shop?utm_medium=ai_doc&utm_campaign=page_md)
- Endpoint: POST https://api.everyinfra.com/api/v1/social with {"platform": "jd", "action": "shop", "params": {...}}
- Price: $0.02881 per call ($28.81 per 1,000 requests); failed calls and empty results are not charged
- Billing unit: every 24 rows you ask for count as one call; blocks that come back with no rows are not charged
- Returns: list, default 24, max 60 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 24 rows, tokens last 24 hours; up to 168 rows
- Mode: sync; add "mode": "async" for slow tasks

店铺资料按 `shop_id` 读取一个京东店铺里的商品行：商品 `item_id`、标题 `title`、价格 `price` 和 `currency`、主图 `image_url`、是否可售 `available`，每行还带店铺自己的 `shop_id`、`shop_name` 和 `shop_url`。它回答「这家店在卖什么、定价在什么位置」，适合盯竞品店铺的商品与定价，或者给选品调研建一份店铺商品清单。

`shop_id` 是数字字符串，不是商品 ID，也不是店铺名称；也可以填不带 query 和 fragment 的店铺链接 https://mall.jd.com/index-<数字>.html。目前一次最多 24 条，默认也是 24 条。

## Health

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

## Parameters

| name | type | required | default | description |
|---|---|---|---|---|
| shop_id | not declared | yes | not declared | 京东店铺数字 ID，或不带 query/fragment 的 https://mall.jd.com/index-<数字>.html；不是商品 ID。 |
| page | integer | no | not declared | 店铺商品的页码，整数；不传或传 1 就是第 1 页。取值范围是 1 到 168 ÷ limit（向上取整）：默认 limit 24 时 1–7，limit 60 时 1–3。用 page 时，每页条数就是这次请求的 limit（1–60）。每一页都按第 1 页的价收，只按这一页自己的条数分档，每 24 条算一次调用：limit 24 时每页算 1 次；limit 60 时每页 60 条算 3 次，最后一页（第 121–168 条，48 条）算 2 次。用 page=N 直接跳到第 N 页，这一次按 N 页收，和一页页翻到第 N 页收得一样（前面 N − 1 页按整页算，加上第 N 页本身）：limit 24、page 5 算 5 次调用；limit 60、page 3 算 3 + 3 + 2 = 8 次调用。第 N 页没返回的条数对应的档退回；第 N 页是空的（比如列表没那么长），整次不扣费。page 超出范围、是 0、负数、小数、字符串（如 "2"）或布尔值时，扣费前返回 422，不扣费。同步请求就能翻到最深那一页（第 168 条），不用加 "mode": "async"。最深那一页（limit 24 时是第 7 页）没有 next_page_token，pagination.stop_reason 为 depth_limit；列表本来就短、翻到头时为 end_of_list。第 1 页每次都现取。第 2 页起从一份保存下来的完整列表（最多 168 条）里按顺序切；第一次要第 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 页的价收，只按这一页自己的条数分档，每 24 条算一次调用：limit 24 时每页算 1 次，翻到第 5 页一共 5 次调用；limit 60 时每页 60 条算 3 次，最后一页（第 121–168 条，48 条）算 2 次。没返回的条数对应的档退回，一条都没返回的空页（比如翻过了短列表的末页）不扣费。最多翻到第 168 条（limit 24 时是 7 页），同步请求就能翻到，不用加 "mode": "async"。第 168 条所在的那一页没有 next_page_token，pagination.stop_reason 为 depth_limit；列表本来就短、翻到头时为 end_of_list。第 1 页每次都现取。第 2 页起从一份保存下来的完整列表（最多 168 条）里按顺序切；第一次要第 2 页或更后面的页时，这份列表最多是一小时前的。用 page_token 从第 1 页一路翻下去，后面每一页都从同一份列表里切：第 1 页已经给过的商品不再出现，中间也不漏，所以各页之间没有重复的商品。翻得慢也一样，这条令牌链一直用它第一次到第 2 页时的那一份。pagination.page 是这一页的页码；pagination.has_more 为 true 就还有下一页，把 next_page_token 作为 page_token 传回。按页码要到的页也会给 next_page_token，下一次带不带 page 都能用它。 |
| limit | integer (1–60) | no | 24 | 这次调用最多返回的条数，整数，1–60；不传按默认值，实际返回可能少于这个数。超过上限会在扣费前返回 422。 |

## Response fields (items in `results`)

| field | meaning |
|---|---|
| item_id | 京东商品数字 ID；search 可把它直接交给详情、评价或价格能力。 |
| url | 该记录在原平台上的可访问链接。 |
| title | 标题。平台无标题概念时（如纯文本帖）为 null。 |
| price | 价格数值，不含货币符号；币种见 currency。 |
| currency | 价格币种代码（如 CNY、USD）。price 存在但 currency 为 null 时不要假定币种。 |
| shop_id | 京东店铺数字 ID。 |
| shop_name | 公开店铺名称。 |
| shop_url | 京东店铺公开页面。 |
| image_url | 图片链接：search、product_detail、shop、skus 里是商品主图（封面）；description_images 里是这一行的那张详情图（京东图床的 https 原图）。 |
| available | 采集时是否可售（product_detail、product_price、shop 的商品行）；缺货时为 false，null 表示页面没给。 |
| 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": "shop",
  "params": {
    "shop_id": "1000004259"
  }
}'
```

```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": "shop",
        "params": {
            "shop_id": "1000004259",
        },
    },
    timeout=120,
)
print(response.status_code)
print(response.json())
```

## Response example

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

```text
{
  "id": "req_…",
  "platform": "jd",
  "action": "shop",
  "results": [
    {
      "item_id": "100386940168",
      "url": "https://item.jd.com/100386940168.html",
      "title": "HUAWEIWATCH GT7Pro碳晶黑46mm钛合金&纳米微晶陶瓷户外进阶运动21天超长续航华为智能手表",
      "price": 2688,
      "currency": "CNY",
      "shop_id": "1000004259",
      "shop_name": "华为京东自营旗舰店",
      "shop_url": "https://mall.jd.com/index-1000004259.html",
      "image_url": "https://img14.360buyimg.com/n0/jfs/t1/550965/17/7947/140219/6ae2b424F7cc9d94c/00835a05a09af40b.jpg",
      "platform": "jd"
    },
    {
      "item_id": "100343412080",
      "url": "https://item.jd.com/100343412080.html",
      "title": "华为MateBook 14 鸿蒙版笔记本电脑 国家补贴 2.8K OLED触控屏 鸿蒙AI 24GB 1TB原野绿 圆键盘",
      "price": 7599,
      "currency": "CNY",
      "shop_id": "1000004259",
      "shop_name": "华为京东自营旗舰店",
      "shop_url": "https://mall.jd.com/index-1000004259.html",
      "image_url": "https://img14.360buyimg.com/n0/jfs/t1/537470/34/12588/89809/6acef399F2a2483a1/00835a05a01f9084.jpg",
      "platform": "jd"
    }
  ],
  "next_page_token": …,
  "pagination": { … },
  "count": 24,
  "billing": {
    "charged": …,
    "charged_usd": …,
    "balance_after_usd": …,
    …
  },
  "quota": { … }
}
```

## FAQ

### 店里的商品超过 24 个怎么办？

目前最多 24 条，这一页也没有翻页参数，所以店里商品更多时，一次只能读到其中一部分。做竞品监测时，要把这个上限写进口径，不要把返回的条数当作这家店的商品总数。

### `shop_id` 在哪里找，能填店铺名称吗？

不能填店铺名称，也不能填商品 ID。要填店铺的数字 ID，或者店铺链接 https://mall.jd.com/index-<数字>.html，链接里 index- 后面的数字就是 `shop_id`。链接不要带 query 或 fragment。

### 读到商品行之后，怎么看单个商品的缺货原因？

把行里的 `item_id` 交给商品价格那一页，单个商品的价格、币种和可售状态都在那里，缺货时还有京东页面给出的原因。这一页的 `image_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
