58 同城item_search接口（官方标准命名58 同城.item.search）是按多维度条件筛选本地生活全品类信息列表的核心检索接口，覆盖房产、招聘、二手车、二手物品、家政服务等主流业务线。该接口采用HTTPS+AppKey/Secret 签名认证，支持 JSON/XML 双格式返回，具备筛选维度丰富、多业务线适配、数据实时性强的特点，是联动item_get接口获取详情的前置依赖。本攻略从接口认知、权限准备、实操对接、调试排错到生产级优化，提供全链路标准化指导。
一、接口核心认知：功能与适配场景
1. 接口定位与核心价值
- 核心功能：输入城市编码、业务线分类、关键词、价格区间等筛选条件，返回分页信息列表；支持按发布时间、价格、热度等维度排序，单页最大返回 50 条数据；可联动
city_list接口获取标准城市编码，实现精准地域筛选。 - 58 同城数据特性
- 多业务线统一适配：一套接口支持所有本地生活品类检索，无需为不同业务线单独对接接口，降低集成成本；
- 筛选维度贴合用户需求：针对不同品类提供专属筛选条件（如房产支持户型 / 朝向筛选、二手车支持品牌 / 里程筛选）；
- 数据实时性强：信息上架、下架、价格调整等动态数据1 分钟内同步，保障列表数据时效性；
- 权限分级管控：基础列表数据对所有权限开放，敏感筛选条件（如个人房源、急售信息）需企业资质授权。
- 典型应用场景
- 本地生活服务平台：构建多品类信息检索页面，支持用户按城市、品类、价格等条件筛选；
- 垂直领域获客工具：针对房产 / 招聘 / 二手车等单一品类，批量获取信息列表，生成目标客户清单；
- 市场行情分析系统：定时检索指定品类信息，统计价格走势、供需变化等市场数据；
- 个性化推荐工具：基于用户历史筛选行为，推送相似条件的信息列表。
2. 核心参数与返回字段
（1）请求参数（GET/POST 提交，需签名认证）
| 参数类型 | 参数名称 | 类型 | 是否必填 | 说明 | 应用示例 |
|---|---|---|---|---|---|
| 公共参数 | app_key | string | 是 | 应用密钥（开放平台获取） | 58_appkey_2026_abc123 |
| secret | string | 是 | 应用秘钥（开放平台获取） | 58_secret_2026_def456 | |
| api_name | string | 是 | 接口名称，固定为item_search | 58同城.item.search | |
| format | string | 否 | 响应格式，默认 JSON | json/xml | |
| v | string | 是 | 接口版本，固定为1.0 | 1.0 | |
| timestamp | string | 是 | 秒级时间戳，与服务器时差≤10 分钟 | 1735689600 | |
| 业务参数 | city_id | string | 是 | 城市编码（从city_list接口获取） | 1（北京）/2（上海） |
| cate_id | string | 是 | 业务线分类 ID | 1（房产）/2（招聘）/3（二手车） | |
| q | string | 否 | 搜索关键词，需 URL 编码 | 两室一厅 地铁房/二手车 大众 | |
| price_min | float | 否 | 最低价格（单位随品类变化） | 房产（万元）/ 招聘（元 / 月）/ 二手车（万元） | |
| price_max | float | 否 | 最高价格 | 同上 | |
| sort_type | string | 否 | 排序方式 | pub_time_desc（最新发布）/price_asc（低价优先）/hot_desc（热度优先） | |
| page_num | int | 否 | 页码，默认 1 | 2 | |
| page_size | int | 否 | 单页条数，默认 20，最大 50 | 50 | |
| filter | string | 否 | 品类专属筛选条件（JSON 格式） | 房产：{"house_style":"2室1厅","orientation":"南向"} |
注意事项
city_id和cate_id为必填业务参数，需分别从city_list接口和开放平台品类文档获取标准值；timestamp参数为秒级时间戳，与服务器时间误差超过 10 分钟会直接导致签名验证失败；filter参数需为标准 JSON 字符串，不同品类的筛选字段不同，需参考官方文档传入；- 签名生成需包含
