# JD.com Search API (jd.search)

- Canonical page: [https://everyinfra.com/en/jd-api/search](https://everyinfra.com/en/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

JD.com Search finds JD products by `keyword` and returns each one's item ID, title and short title, price, review count, positive-rating share, shop, whether JD sells it directly, promotion tags and selling points. Use it to see which products come up first on JD for a search, who sells them and how buyers rate them: early product research, a first look at price bands, or comparing JD's own listings with third-party shops.

Chinese keywords usually match JD's product titles more closely. Pass `item_id` from a result to the JD Product details or Reviews capability to dig deeper. `good_rate` is the positive-rating percentage JD publishes and only means much next to the review count; `review_count` and `sold_count` are display text such as 100k+, not exact numbers.

## 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 | Specifies the search query for JD.com `search`. This must be a search phrase, not an item ID or shop selector, and matching results do not imply exhaustive catalog coverage. |
| page | integer | no | not declared | Page number of the results, an integer; leave it out or send 1 for the first page. It runs from 1 to 150 ÷ `limit`, rounded up: 1–5 at `limit` 30, 1–30 at the default `limit` 5, 1–15 at `limit` 10. With `page`, the page size is the `limit` of this request (1–30). Every page is billed at the price of page 1, tiered by the rows on that page alone, one call per 5 rows: at `limit` 30 a page of 30 rows is 6 calls, at `limit` 5 a page is 1 call. Asking for `page` N directly bills N pages, the same as paging from page 1 to page N (the N − 1 pages before it as full pages, plus page N itself): `limit` 30 with `page` 5 is 30 calls in one request. Blocks for rows of page N that did not come back are refunded, and nothing is charged for the request if page N is empty (for example, the list is not that long). A `page` that is out of range, 0, negative, fractional, a string such as "2" or a boolean is rejected with 422 before charging. A sync call reaches the deepest page, row 150; you do not need `"mode": "async"`. The deepest page (page 5 at `limit` 30) has no `next_page_token` and `pagination.stop_reason` is `depth_limit`; a list that is simply shorter ends with `end_of_list`. Page 1 is fetched fresh on every request. From page 2 on, rows are cut in order from one saved full list (up to 150 rows), and when you first ask for page 2 or later that list is at most one hour old. A page requested with `page` is cut from that list by its original position (page N is the `limit` rows starting at row (N − 1) × `limit` + 1); it does not know what the page 1 you got earlier looked like, so between a separately fetched page 1 and it, or between pages requested across an hour boundary, a few products can repeat or be missing: dedupe by `item_id` when merging. To read the whole list with no repeats, start at page 1 and follow `next_page_token`. `pagination.page` is the page number of this page, and `pagination.has_more` true means there is a next page: ask for `page` + 1, or pass `next_page_token` back as `page_token`. When both `page` and `page_token` are sent, `page_token` wins. A page requested with `page` also returns a `next_page_token`; the next call can use it with or without `page`. |
| page_token | not declared | no | not declared | Page token. Leave it out for the first page. When the response has a `next_page_token`, pass it back as `page_token`, exactly as received, to get the next page, with the other parameters unchanged. Every page keeps the page size of the `limit` of the request that returned the token, and a later `limit` has no effect. You can also skip the token and ask for a page number with `page`; when both are sent, `page_token` wins. A token is valid for 24 hours and works only for the same parameters and the same account; a token used with other parameters is rejected with 422 and not charged. Every page is billed at the price of page 1, tiered by the rows on that page alone, one call per 5 rows: at `limit` 30 a page of 30 rows is 6 calls, so paging to page 5 is 5 pages and 30 calls; at `limit` 5 each page is 1 call. Blocks for rows that did not come back are refunded, and an empty page (for example, past the end of a short list) is not charged. Paging stops at row 150 (5 pages at `limit` 30), and a sync call gets there: you do not need `"mode": "async"`. The page that holds row 150 has no `next_page_token` and `pagination.stop_reason` is `depth_limit`; a list that is simply shorter ends with `end_of_list`. Page 1 is fetched fresh on every request. From page 2 on, rows are cut in order from one saved full list (up to 150 rows), and when you first ask for page 2 or later that list is at most one hour old. When you page from page 1 with `page_token`, every later page is cut from that same list: products already given on page 1 do not come back and nothing is skipped in between, so there are no repeats between pages. Slow paging makes no difference: the token chain keeps using the list it had when it first reached page 2. `pagination.page` is the page number of this page, and `pagination.has_more` true means there is a next page: pass `next_page_token` back as `page_token`. A page requested with `page` also returns a `next_page_token`; the next call can use it with or without `page`. |
| limit | integer (1–30) | no | 5 | The most rows to return in this call, an integer from 1 to 30. 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 |
|---|---|
| item_id | JD numeric product ID. From search results you can pass it straight to detail, reviews, or price calls. |
| url | Link to the record on the platform. |
| title | Title. null when the platform has no titles (for example text-only posts). |
| short_title | Short product title as JD returns it. |
| price | Price as a number without a currency symbol; see currency. |
| currency | Currency code of the price (for example CNY, USD). If price is present but currency is null, do not assume a currency. |
| sold_count | Sales figure as shown in search results (search): display text such as 100k+, not an exact unit count. |
| review_count | Review count as shown in search results (search): display text that may be rounded, not an exact count. |
| good_rate | Public positive-review percentage shown by JD. |
| shop_id | JD numeric shop ID. |
| shop_name | Public shop name. |
| shop_url | Public JD shop page. |
| is_jd_self | Whether this is a JD self-operated (JD.com retail) product. |
| promotion | Promotion label from the product list. |
| sell_point | Public selling points from the product list. |
| category_ids | JD category ID path. |
| image_url | Image URL: in search, product_detail, shop and skus it is the product's main (cover) image; in description_images it is the description image of that row (the full-size https image on JD's image host). |
| 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": "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

### Can I search in English?

Yes, but Chinese keywords usually match the product titles on JD more closely and return better hits. When you search for a brand and model, write it the way it tends to appear in JD product titles.

### How do I get details and reviews for a result?

Each result's `item_id` is the numeric JD product ID. Pass it straight to the JD Product details, Reviews or Product price capability; there is no need to build a product link first.

### How do I tell JD's own listings from third-party shops?

Check `is_jd_self`: true means JD sells the product itself. Shop details are in `shop_name`, `shop_id` and `shop_url`. Comparing prices and ratings within each group is fairer than mixing them.

## 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
