{ "openapi": "3.1.0", "info": { "title": "JD.com Product Search API (V3)", "version": "v0", "description": "Search JD.com products by keyword, including products in advertising placements, with category filtering, pagination, sorting and price-range filters. Use it to research sponsored product visibility and discover products within a selected category." }, "servers": [ { "url": "https://api.justoneapi.com", "description": "Global production API (default)" } ], "tags": [ { "name": "JD.com", "description": "JD.com product details, reviews, and store catalog data for commerce intelligence and catalog monitoring.", "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": [ "JD.com" ], "summary": "Product Search", "description": "Search JD.com products by keyword, including products in advertising placements, with category filtering, pagination, sorting and price-range filters. Use it to research sponsored product visibility and discover products within a selected category.", "operationId": "getApiJdSearchItemListV3", "parameters": [ { "name": "token", "in": "query", "description": "Access token for this API service.", "required": true, "schema": { "type": "string" } }, { "name": "keyword", "in": "query", "description": "Search keyword. Required even when a category is selected.", "required": true, "schema": { "type": "string" } }, { "name": "cid", "in": "query", "description": "Numeric category ID used to filter the search results.", "required": false, "schema": { "type": "string" } }, { "name": "cidLevel", "in": "query", "description": "Category ID level: 1 for a first-level category, 2 for a second-level category, or 3 for a third-level category.\n\nAvailable Values:\n- `1`: First-level category\n- `2`: Second-level category\n- `3`: Third-level category", "required": false, "schema": { "type": "string", "description": "JD.com category ID level", "enum": [ "1", "2", "3" ] } }, { "name": "page", "in": "query", "description": "Page number, starting at 1.", "required": false, "schema": { "type": "string" } }, { "name": "sort", "in": "query", "description": "Sort order for the search results.\n\nAvailable Values:\n- `0`: Comprehensive sorting\n- `1`: Sort by sales volume\n- `2`: Price, highest first\n- `3`: Price, lowest first\n- `6`: Sort by comments", "required": false, "schema": { "type": "string", "description": "JD.com product search sort order", "enum": [ "0", "1", "2", "3", "6" ] } }, { "name": "priceInterval", "in": "query", "description": "Price range in minimum-maximum format, for example 0-100. Both values must be non-negative and the minimum must not exceed the maximum.", "required": false, "schema": { "type": "string" } }, { "name": "brand", "in": "query", "description": "Brand name, for example iQOO or iPhone.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "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": "Invalid request parameters or body", "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": "Invalid or inactive access token", "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": "Permission denied", "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": "Request rate or daily quota limit exceeded", "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": "Internal server error", "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": "Service temporarily unavailable", "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": "Advertising placements", "content": "Search results include products in advertising placements.", "concept": "advertising_placements", "aliases": [ "advertising placements", "sponsored products", "广告位商品", "广告商品" ] }, { "type": "info", "kind": "CAPABILITY", "title": "Category filtering", "content": "Filter products by category using cid and the optional cidLevel parameter.", "concept": "category_filter", "aliases": [ "category filtering", "category search", "分类筛选", "类目筛选" ] }, { "type": "warning", "kind": "GUIDANCE", "title": "Success rate and retries", "content": "This API has a relatively low collection success rate. Retry the request if data collection fails.", "concept": "failure_retry", "aliases": [ "low success rate", "retry on failure", "成功率偏低", "失败重试" ] } ], "x-endpoint-family": "jd_search_item_list" } } } }