## 搜索商品数据(goodsSearch) >[info] 场景说明:根据条件获取复杂的商品数据,并提供当前搜索条件下,还能继续细化检索的数据列表,如果是简单的获取商品列表,请使用:获取商品列表(goodsList)接口,速度更快! ### 是否需要获取用户TOKEN `否` ***** ### 请求地址 ``` POST http://api.xxx.com/goods/search ``` ### 公共请求参数 | 字段 | 类型 | 是否必填 | 描述 | | --- | --- | --- | --- | | appid | string | 必须 | 平台提供的唯一APPID | | version | string | 必须 | 接口版本号,固定填:v3 | | sign\_type | string | 必须 | 签名类型,目前只支持md5 | | timestamp | string | 必须 | 发起时间戳,格式为:yyyy-mm-dd hh::ii::ss | | format | string | 必须 | 返回的数据格式,只支持json | | sign | string | 必须 | 请求参数的签名,请参考:[签名规则](signature.md) | | token | string | 必须 | 访问TOKEN | | params | string | 必须 | 请求参数的集合,除公共参数外,所有请求参数都必须放在这个参数中传递,json\_encode后送入 | 应用请求参数`params`格式 | 字段 | 类型 | 是否必填 | 描述 | | --- | --- | --- | --- | | cate\_id | integer | 可选 | 商品分类ID,包含下级分类的商品 | | store\_id | integer | 可选 | 店铺ID,如果不传,则不限制 | | keyword | string | 可选 | 关键词,模糊查询 | | recommended | integer | 可选 | 推荐标识,1=推荐的商品,0=非推荐的商品 | | orderby | string | 可选 | 排序,参考下文:排序取值说明 | | if\_show | integer | 可选 | 是否上架,1=取上架的商品,0=取下架的商品,不传则不限制 | | closed | integer | 可选 | 是否禁售,1=取禁售的商品,0=取可售的商品 | | brand | string | 可选 | 品牌,完全匹配 | | price | string | 可选 | 价格区间,如:0-1000 | | region\_id | integer | 可选 | 所在地区,同店铺所在的地区匹配 | | props | string | 可选 | 商品属性,参考下文:商品属性取值说明 | | page | integer | 可选 | 当前页 | | page\_size | integer | 可选 | 每页读取多少条记录,默认10条 | >[info] orderby排序取值说明:"sales|desc"=销量从高到低,"price|desc"=价格从高到低,"price|asc"=价格从低到高,"views|desc"=点击量从高到低,"add\_time|desc"=上架时间从近到远,"add\_time|asc"=上架时间从远到近,"comments|desc"=评论数从多到少 >[info] props商品属性取值说明:格式为 "属性名ID:属性值ID",如:67:89,如果一次检索条件有多个属性,则用竖线隔开,如:67:89|68:209|55:234 ### 请求示例 ``` { "appid": "您的APPID", "version": "v3", "sign_type": "md5", "timestamp": "2020-8-10 12:00:00", "format": "json", "sign": "op0987yhjmngt54rtg2wgdfvcder2765", "params": { "cate_id": 21, "orderby": "price|desc", "props": "67:89|68:209|55:234", "price": "100-999" } } ``` ***** ### 公共返回参数 | 字段 | 类型 | 是否必填 | 描述 | | --- | --- | --- | --- | | code | integer | 必须 | 0=成功,其它值代表请求失败的错误代码,请参考:[公共错误码](response-code.md) | | message | string | 必须 | 请求成功/失败的描述信息 | | \+ data | array | 必须 | 返回结果,如果没有数据则返回空 | | └ list | list | 必须 | 商品列表 | | └ pagination | array | 必须 | 分页信息 | | └ selectors | array | 必须 | 可供继续细化检索的参数列表 | | └ filters | array | 可选 | 目前已检索的条件列表 | 返回`data->list`参数格式 | 字段 | 类型 | 是否必填 | 描述 | | --- | --- | --- | --- | | goods\_id | integer | 必须 | 商品ID | | goods\_name | string | 必须 | 商品名称 | | cate\_id | integer | 必须 | 分类ID | | cate\_name | string | 必须 | 分类名称 | | store\_id | integer | 必须 | 店铺ID | | store\_name | string | 必须 | 店铺名称 | | brand | string | 可选 | 品牌 | | default\_spec | integer | 必须 | 规格ID,默认SKU | | price | decimal | 必须 | 默认SKU的商品价格 | | mkprice | decimal | 可选 | 市场价格 | | stock | integer | 必须 | 默认SKU库存量 | | default\_image | string | 必须 | 商品主图 | | other\_image | string\[\] | 可选 | 商品从图,格式为:\["a.jpg","b.jpg"\] | | recommended | integer | 可选 | 是否为推荐商品 | | views | integer | 可选 | 点击量 | | sales | integer | 可选 | 销售量 | | collects | integer | 可选 | 收藏量 | | comments | integer | 可选 | 评论量 | | add\_time | string | 必须 | 商品发布时间,格式:yyyy-mm-dd hh:ii:ss | | dt\_id | integer | 必须 | 运费模板ID | | if\_show | integer | 必须 | 是否上架,1=上架,0=下架 | | closed | integer | 必须 | 是否禁售,1=禁售,0=可售 | 返回`data->pagination`参数格式 | 字段 | 类型 | 是否必填 | 描述 | | --- | --- | --- | --- | | page | integer | 必须 | 当前页 | | page\_size | integer | 必须 | 每一页显示的数据量 | | page\_count | integer | 必须 | 总页数 | | total | integer | 必须 | 总记录数 | 返回`data->selectors`参数格式 | 字段 | 类型 | 是否必填 | 描述 | | --- | --- | --- | --- | | \+ by\_category | list | 可选 | 当前条件下,还能细化检索的分类列表 | | └ cate\_id | integer | 必须 | 商品分类ID | | └ cate\_name | string | 必须 | 商品分类名称 | | └ count | integer | 必须 | 符合该条件下的商品数 | | \+ by\_brand | list | 可选 | 当前条件下,还能细化检索的品牌列表 | | └ brand | string | 必须 | 品牌名称 | | └ brand\_logo | string | 必须 | 品牌logo | | └ count | integer | 必须 | 符合该条件下的商品数 | | \+ by\_price | list | 可选 | 当前条件下,还能细化检索的价格区间 | | └ value | string | 必须 | 价格区间值,如:100-200 | | └ name | string | 必须 | 价格区间显示的名称 | | └ count | integer | 必须 | 符合当前条件的商品数 | | \+ by\_region | list | 可选 | 当前条件下,还能细化检索的地区列表 | | └ region\_id | integer | 必须 | 地区ID | | └ regin\_name | string | 必须 | 地区名称 | | └ count | integer | 必须 | 符合该条件下的商品数 | | \+ by\_prop | list | 可选 | 当前条件下,还能细化检索的属性列表 | | └ pid | integer | 必须 | 属性ID | | └ name | string | 必须 | 属性名 | | └ is\_color | boolean | 必须 | 是否颜色属性 | | └+ values | list | 必须 | 该属性的值列表 | | <span>   </span>└ vid | integer | 必须 | 属性值ID | | <span>   </span>└ pid | integer | 必须 | 属性名ID | | <span>   </span>└ val | string | 必须 | 属性值,如:黑色 | | <span>   </span>└ color | string | 可选 | 颜色值,如:#000000,当是颜色属性的时候才有值 | | <span>   </span>└ count | integer | 必须 | 符合该条件下的商品数 | >[success] count: 指当前条件下有多少个商品在售。data->selectors数据主要是用于,在当前搜索条件下,还有哪些搜索条件可用,为进一步筛选商品提供数据 返回`data->filters`参数格式 | 字段 | 类型 | 是否必填 | 描述 | | --- | --- | --- | --- | | \+ category | array | 可选 | 当前已选择的分类 | | └ key | string | 必须 | 参数字段,固定为:cate\_id | | └ name | string | 必须 | 参数名称 | | └ value | string | 必须 | 参数值 | | \+ region | array | 可选 | 当前已选择的地区 | | └ key | string | 必须 | 参数字段,固定:region\_id | | └ name | string | 必须 | 参数名称 | | └ value | integer | 必须 | 参数值,地区ID | | \+ brand | array | 可选 | 当前已选择的品牌 | | └ key | string | 必须 | 参数字段,固定:brand | | └ name | string | 必须 | 参数名称 | | └ value | string | 必须 | 参数值 | | \+ price | array | 可选 | 当前已选择的价格区间 | | └ key | string | 必须 | 参数字段,固定:price | | └ name | string | 必须 | 参数名称,价格区间 | | └ value | string | 必须 | 参数值 | | \+ keyword | array | 可选 | 当前已搜到的关键词 | | └ key | string | 必须 | 参数字段,固定:keyword | | └ name | string | 必须 | 参数名称 | | └ value | string | 必须 | 参数值 | | \+ props\[属性名ID\] | array | 可选 | 已选择的属性(有多个) | | └ key | string | 必须 | 参数值ID组合,如:70:90 | | └ name | string | 必须 | 参数名称 | | └ value | string | 必须 | 参数值 | >[warning] 注释:表格中的 “+ ”、“└ + ”、“└ ”代表的是字段层级关系,并非字段名。props\[属性名ID\]表示会有多个属性条件,分别以ID作为后缀,如:props68,props69等。data->filters数据主要是用于设置选中效果。 ### 返回数据示例 ``` { "code": 0, "message": "成功", "data": { "list": [ { "goods_id": 123, "goods_name": "Midea/美的 BCD-213TM(E) 节能静音家用三开门小冰箱小型电冰箱", "cate_id": 1219, "cate_name": "冰箱", "store_id":2, "store_name": "演示店铺", "brand": "美的", "recommended": 1, "default_image": "http://www.xxx.com/data/files/store_2/goods/20181121212111599.jpg", "other_image": { "http://www.xxx.com/data/files/store_2/goods/20181121123176125.jpg", "http://www.xxx.com/data/files/store_2/goods/20134543123176123.jpg" }, "default_spec": 135, "price": 149.99, "mkprice": 200.00, "stock": 700, "if_show": 1, "closed": 0, "views": 100, "sales": 20, "collects": 89, "comments": 5, "add_time": "2020-1-9 15:40:49", "dt_id": 0 }, { "goods_id": 124, "goods_name": "Haier/海尔 BCD-206STPA 206升三门冷藏小型家用节能小冰箱软冷冻", "cate_id": 1219, "cate_name": "冰箱", "store_id":2, "store_name": "演示店铺", "brand": "海尔", "recommended": 1, "default_image": "http://www.xxx.com/data/files/store_2/goods/20181121212111597.jpg", "other_image": "", "default_spec": 136, "price": 249.99, "mkpice": 300.00, "stock": 678, "views": 130, "sales": 26, "collects": 59, "comments": 8, "add_time": "2020-4-9 10:46:40", "dt_id: 2 } ], "pagination": { "page":1, "page_size":10, "page_count":1, "total":2 }, "selectors": { "by_category":[ { "cate_id": 22, "cate_name": "大家电", "count": 10, } ], "by_brand": [ { "brand": "华为", "brand_logo": "logo.jpg", "count": 2, } ], "by_region": [ { "region_id": 343, "regin_name": "广西壮族自治区 南宁", "count": 10 } ], "by_price": [ { "value": "100-999", "name": "100-999", "count": 10 } ], "by_prop": [ { "pid": 69, "name": "颜色", "is_color": 1, "values": [ { "vid": 199, "pid": 69, "val": "黑色", "color": "#000000", "count": 2, }, { "vid": 200, "pid": 69, "val": "红色", "color": "#ff6600", "count": 4, } ] }, { "pid": 70, "name": "风格", "is_color":0, "values": [ { "vid": 300, "pid": 70, "val": "韩版", "color": "", "count": 4 } ] } ] }, "filters": { "props70": { "key": "70:300", "name": "风格", "value": "韩版" }, "category": { "key": "cate_id", "name": "分类", "value": "大家电" } "brand": { "key": "brand", "name": "品牌", "value": "华为" }, "keyword": { "key": "keyword", "name": "关键词", "value": "华为matebook" }, "price" : { "key": "price", "name": "价格区间", "value": "2000-4000" }, "region": { "key": "region_id", "name": "地区", "value": 1221 } } } } ```