{ "openapi": "3.1.0", "info": { "title": "京东商品搜索 API (V3)", "version": "v0", "description": "按关键词搜索京东商品，包括广告位中的商品，支持类目筛选、分页、排序和价格区间筛选。用于研究赞助商品的曝光情况，并在所选类目中发现商品。" }, "servers": [ { "url": "https://api.justoneapi.com", "description": "全球生产 API（默认）" } ], "tags": [ { "name": "京东", "description": "京东商品详情、评价和店铺目录数据，用于商业情报和目录监控。", "x-platform-id": "jdcom", "x-platform-aliases": [ "JD.com", "JD", "京东" ], "x-platform-detection-aliases": [ "JD.com", "JD", "京东" ] } ], "paths": { "/api/jd/search-item-list/v3": { "get": { "tags": [ "京东" ], "summary": "商品搜索", "description": "按关键词搜索京东商品，包括广告位中的商品，支持类目筛选、分页、排序和价格区间筛选。用于研究赞助商品的曝光情况，并在所选类目中发现商品。", "operationId": "getApiJdSearchItemListV3", "parameters": [ { "name": "token", "in": "query", "description": "此 API 服务的访问令牌。", "required": true, "schema": { "type": "string" } }, { "name": "keyword", "in": "query", "description": "搜索关键词。即使已选择类目，此参数也为必填。", "required": true, "schema": { "type": "string" } }, { "name": "cid", "in": "query", "description": "用于筛选搜索结果的数字类目 ID。", "required": false, "schema": { "type": "string" } }, { "name": "cidLevel", "in": "query", "description": "类目 ID 层级：1 表示一级类目，2 表示二级类目，3 表示三级类目。\n\n可用值：\n- `1`：一级类目\n- `2`：二级类目\n- `3`：三级类目", "required": false, "schema": { "type": "string", "description": "京东类目 ID 层级", "enum": [ "1", "2", "3" ] } }, { "name": "page", "in": "query", "description": "页码，从1开始。", "required": false, "schema": { "type": "string" } }, { "name": "sort", "in": "query", "description": "搜索结果的排序方式。\n\n可用值：\n- `0`：综合排序\n- `1`：按销量排序\n- `2`：价格从高到低\n- `3`：价格从低到高\n- `6`：按评论排序", "required": false, "schema": { "type": "string", "description": "京东商品搜索排序方式", "enum": [ "0", "1", "2", "3", "6" ] } }, { "name": "priceInterval", "in": "query", "description": "价格范围，采用最小值-最大值格式，例如 0-100。两个值必须为非负数，且最小值不得超过最大值。", "required": false, "schema": { "type": "string" } }, { "name": "brand", "in": "query", "description": "品牌名称，例如 iQOO 或 iPhone。", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "好的", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "format": "int32", "enum": [ 0, 100, 101, 202, 300, 301, 302, 303, 400, 404, 500, 503, 600, 601, 602 ] }, "message": { "type": [ "string", "null" ] }, "data": {}, "recordTime": { "type": [ "string", "null" ] }, "requestId": { "type": "string" }, "reason": { "type": "string" }, "requestParams": { "type": "object", "properties": { "query": { "type": "object", "additionalProperties": { "type": "object" } }, "body": { "type": "object", "properties": { "empty": { "type": "boolean" }, "array": { "type": "boolean" }, "null": { "type": "boolean" }, "object": { "type": "boolean" }, "float": { "type": "boolean" }, "string": { "type": "boolean" }, "missingNode": { "type": "boolean" }, "valueNode": { "type": "boolean" }, "container": { "type": "boolean" }, "pojo": { "type": "boolean" }, "short": { "type": "boolean" }, "int": { "type": "boolean" }, "long": { "type": "boolean" }, "double": { "type": "boolean" }, "bigDecimal": { "type": "boolean" }, "bigInteger": { "type": "boolean" }, "textual": { "type": "boolean", "deprecated": true }, "boolean": { "type": "boolean" }, "binary": { "type": "boolean" }, "nodeType": { "type": "string", "enum": [ "ARRAY", "BINARY", "BOOLEAN", "MISSING", "NULL", "NUMBER", "OBJECT", "POJO", "STRING" ] }, "integralNumber": { "type": "boolean" }, "floatingPointNumber": { "type": "boolean" }, "number": { "type": "boolean" }, "embeddedValue": { "type": "boolean" } } } } } }, "required": [ "code", "data", "message", "recordTime" ] } } } }, "400": { "description": "请求参数或请求体无效", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "format": "int32", "enum": [ 0, 100, 101, 202, 300, 301, 302, 303, 400, 404, 500, 503, 600, 601, 602 ] }, "message": { "type": [ "string", "null" ] }, "data": {}, "recordTime": { "type": [ "string", "null" ] }, "requestId": { "type": "string" }, "reason": { "type": "string" }, "requestParams": { "type": "object", "properties": { "query": { "type": "object", "additionalProperties": { "type": "object" } }, "body": { "type": "object", "properties": { "empty": { "type": "boolean" }, "array": { "type": "boolean" }, "null": { "type": "boolean" }, "object": { "type": "boolean" }, "float": { "type": "boolean" }, "string": { "type": "boolean" }, "missingNode": { "type": "boolean" }, "valueNode": { "type": "boolean" }, "container": { "type": "boolean" }, "pojo": { "type": "boolean" }, "short": { "type": "boolean" }, "int": { "type": "boolean" }, "long": { "type": "boolean" }, "double": { "type": "boolean" }, "bigDecimal": { "type": "boolean" }, "bigInteger": { "type": "boolean" }, "textual": { "type": "boolean", "deprecated": true }, "boolean": { "type": "boolean" }, "binary": { "type": "boolean" }, "nodeType": { "type": "string", "enum": [ "ARRAY", "BINARY", "BOOLEAN", "MISSING", "NULL", "NUMBER", "OBJECT", "POJO", "STRING" ] }, "integralNumber": { "type": "boolean" }, "floatingPointNumber": { "type": "boolean" }, "number": { "type": "boolean" }, "embeddedValue": { "type": "boolean" } } } } } }, "required": [ "code", "data", "message", "recordTime" ] } } } }, "401": { "description": "访问令牌无效或未激活", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "format": "int32", "enum": [ 0, 100, 101, 202, 300, 301, 302, 303, 400, 404, 500, 503, 600, 601, 602 ] }, "message": { "type": [ "string", "null" ] }, "data": {}, "recordTime": { "type": [ "string", "null" ] }, "requestId": { "type": "string" }, "reason": { "type": "string" }, "requestParams": { "type": "object", "properties": { "query": { "type": "object", "additionalProperties": { "type": "object" } }, "body": { "type": "object", "properties": { "empty": { "type": "boolean" }, "array": { "type": "boolean" }, "null": { "type": "boolean" }, "object": { "type": "boolean" }, "float": { "type": "boolean" }, "string": { "type": "boolean" }, "missingNode": { "type": "boolean" }, "valueNode": { "type": "boolean" }, "container": { "type": "boolean" }, "pojo": { "type": "boolean" }, "short": { "type": "boolean" }, "int": { "type": "boolean" }, "long": { "type": "boolean" }, "double": { "type": "boolean" }, "bigDecimal": { "type": "boolean" }, "bigInteger": { "type": "boolean" }, "textual": { "type": "boolean", "deprecated": true }, "boolean": { "type": "boolean" }, "binary": { "type": "boolean" }, "nodeType": { "type": "string", "enum": [ "ARRAY", "BINARY", "BOOLEAN", "MISSING", "NULL", "NUMBER", "OBJECT", "POJO", "STRING" ] }, "integralNumber": { "type": "boolean" }, "floatingPointNumber": { "type": "boolean" }, "number": { "type": "boolean" }, "embeddedValue": { "type": "boolean" } } } } } }, "required": [ "code", "data", "message", "recordTime" ] } } } }, "403": { "description": "权限不足", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "format": "int32", "enum": [ 0, 100, 101, 202, 300, 301, 302, 303, 400, 404, 500, 503, 600, 601, 602 ] }, "message": { "type": [ "string", "null" ] }, "data": {}, "recordTime": { "type": [ "string", "null" ] }, "requestId": { "type": "string" }, "reason": { "type": "string" }, "requestParams": { "type": "object", "properties": { "query": { "type": "object", "additionalProperties": { "type": "object" } }, "body": { "type": "object", "properties": { "empty": { "type": "boolean" }, "array": { "type": "boolean" }, "null": { "type": "boolean" }, "object": { "type": "boolean" }, "float": { "type": "boolean" }, "string": { "type": "boolean" }, "missingNode": { "type": "boolean" }, "valueNode": { "type": "boolean" }, "container": { "type": "boolean" }, "pojo": { "type": "boolean" }, "short": { "type": "boolean" }, "int": { "type": "boolean" }, "long": { "type": "boolean" }, "double": { "type": "boolean" }, "bigDecimal": { "type": "boolean" }, "bigInteger": { "type": "boolean" }, "textual": { "type": "boolean", "deprecated": true }, "boolean": { "type": "boolean" }, "binary": { "type": "boolean" }, "nodeType": { "type": "string", "enum": [ "ARRAY", "BINARY", "BOOLEAN", "MISSING", "NULL", "NUMBER", "OBJECT", "POJO", "STRING" ] }, "integralNumber": { "type": "boolean" }, "floatingPointNumber": { "type": "boolean" }, "number": { "type": "boolean" }, "embeddedValue": { "type": "boolean" } } } } } }, "required": [ "code", "data", "message", "recordTime" ] } } } }, "429": { "description": "请求速率或每日配额已超限", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "format": "int32", "enum": [ 0, 100, 101, 202, 300, 301, 302, 303, 400, 404, 500, 503, 600, 601, 602 ] }, "message": { "type": [ "string", "null" ] }, "data": {}, "recordTime": { "type": [ "string", "null" ] }, "requestId": { "type": "string" }, "reason": { "type": "string" }, "requestParams": { "type": "object", "properties": { "query": { "type": "object", "additionalProperties": { "type": "object" } }, "body": { "type": "object", "properties": { "empty": { "type": "boolean" }, "array": { "type": "boolean" }, "null": { "type": "boolean" }, "object": { "type": "boolean" }, "float": { "type": "boolean" }, "string": { "type": "boolean" }, "missingNode": { "type": "boolean" }, "valueNode": { "type": "boolean" }, "container": { "type": "boolean" }, "pojo": { "type": "boolean" }, "short": { "type": "boolean" }, "int": { "type": "boolean" }, "long": { "type": "boolean" }, "double": { "type": "boolean" }, "bigDecimal": { "type": "boolean" }, "bigInteger": { "type": "boolean" }, "textual": { "type": "boolean", "deprecated": true }, "boolean": { "type": "boolean" }, "binary": { "type": "boolean" }, "nodeType": { "type": "string", "enum": [ "ARRAY", "BINARY", "BOOLEAN", "MISSING", "NULL", "NUMBER", "OBJECT", "POJO", "STRING" ] }, "integralNumber": { "type": "boolean" }, "floatingPointNumber": { "type": "boolean" }, "number": { "type": "boolean" }, "embeddedValue": { "type": "boolean" } } } } } }, "required": [ "code", "data", "message", "recordTime" ] } } } }, "500": { "description": "服务器内部错误", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "format": "int32", "enum": [ 0, 100, 101, 202, 300, 301, 302, 303, 400, 404, 500, 503, 600, 601, 602 ] }, "message": { "type": [ "string", "null" ] }, "data": {}, "recordTime": { "type": [ "string", "null" ] }, "requestId": { "type": "string" }, "reason": { "type": "string" }, "requestParams": { "type": "object", "properties": { "query": { "type": "object", "additionalProperties": { "type": "object" } }, "body": { "type": "object", "properties": { "empty": { "type": "boolean" }, "array": { "type": "boolean" }, "null": { "type": "boolean" }, "object": { "type": "boolean" }, "float": { "type": "boolean" }, "string": { "type": "boolean" }, "missingNode": { "type": "boolean" }, "valueNode": { "type": "boolean" }, "container": { "type": "boolean" }, "pojo": { "type": "boolean" }, "short": { "type": "boolean" }, "int": { "type": "boolean" }, "long": { "type": "boolean" }, "double": { "type": "boolean" }, "bigDecimal": { "type": "boolean" }, "bigInteger": { "type": "boolean" }, "textual": { "type": "boolean", "deprecated": true }, "boolean": { "type": "boolean" }, "binary": { "type": "boolean" }, "nodeType": { "type": "string", "enum": [ "ARRAY", "BINARY", "BOOLEAN", "MISSING", "NULL", "NUMBER", "OBJECT", "POJO", "STRING" ] }, "integralNumber": { "type": "boolean" }, "floatingPointNumber": { "type": "boolean" }, "number": { "type": "boolean" }, "embeddedValue": { "type": "boolean" } } } } } }, "required": [ "code", "data", "message", "recordTime" ] } } } }, "503": { "description": "服务暂时不可用", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "format": "int32", "enum": [ 0, 100, 101, 202, 300, 301, 302, 303, 400, 404, 500, 503, 600, 601, 602 ] }, "message": { "type": [ "string", "null" ] }, "data": {}, "recordTime": { "type": [ "string", "null" ] }, "requestId": { "type": "string" }, "reason": { "type": "string" }, "requestParams": { "type": "object", "properties": { "query": { "type": "object", "additionalProperties": { "type": "object" } }, "body": { "type": "object", "properties": { "empty": { "type": "boolean" }, "array": { "type": "boolean" }, "null": { "type": "boolean" }, "object": { "type": "boolean" }, "float": { "type": "boolean" }, "string": { "type": "boolean" }, "missingNode": { "type": "boolean" }, "valueNode": { "type": "boolean" }, "container": { "type": "boolean" }, "pojo": { "type": "boolean" }, "short": { "type": "boolean" }, "int": { "type": "boolean" }, "long": { "type": "boolean" }, "double": { "type": "boolean" }, "bigDecimal": { "type": "boolean" }, "bigInteger": { "type": "boolean" }, "textual": { "type": "boolean", "deprecated": true }, "boolean": { "type": "boolean" }, "binary": { "type": "boolean" }, "nodeType": { "type": "string", "enum": [ "ARRAY", "BINARY", "BOOLEAN", "MISSING", "NULL", "NUMBER", "OBJECT", "POJO", "STRING" ] }, "integralNumber": { "type": "boolean" }, "floatingPointNumber": { "type": "boolean" }, "number": { "type": "boolean" }, "embeddedValue": { "type": "boolean" } } } } } }, "required": [ "code", "data", "message", "recordTime" ] } } } } }, "x-order": "19001090", "x-api-version": "v3", "x-docs-slug": "product-search-v3", "x-search-aliases": [ "京东广告位商品搜索", "京东广告商品搜索", "京东分类商品搜索", "JD sponsored product search", "JD category product search" ], "x-highlights": [ { "type": "info", "kind": "CAPABILITY", "title": "广告位", "content": "搜索结果包含广告位中的商品。", "concept": "advertising_placements", "aliases": [ "advertising placements", "sponsored products", "广告位商品", "广告商品" ] }, { "type": "info", "kind": "CAPABILITY", "title": "分类筛选", "content": "使用 cid 和可选的 cidLevel 参数按分类筛选商品。", "concept": "category_filter", "aliases": [ "category filtering", "category search", "分类筛选", "类目筛选" ] }, { "type": "warning", "kind": "GUIDANCE", "title": "成功率与重试", "content": "此 API 的数据采集成功率相对较低。如果数据采集失败，请重试请求。", "concept": "failure_retry", "aliases": [ "low success rate", "retry on failure", "成功率偏低", "失败重试" ] } ], "x-endpoint-family": "jd_search_item_list" } } } }