房天下item_search接口（官方标准命名fang.item.search）是按关键词、区域、户型、价格等多维度筛选房产列表的核心接口，覆盖新房、二手房、租房、商业地产等全品类房源检索，支持分页返回结构化基础数据，可联动item_get接口获取房源详情，适配房产信息平台搭建、市场行情监控、购房需求匹配等场景。该接口采用HTTPS+API Key/Secret 签名认证，支持 JSON/XML 双格式返回，具备数据权威合规、筛选维度灵活、实时性强的特点。本攻略从接口认知、权限准备、实操对接、调试排错到生产级优化，提供全链路标准化指导。
一、接口核心认知：功能与适配场景
1. 接口定位与核心价值
- 核心功能：输入关键词（如 “北京朝阳 三居室 地铁房”），搭配区域、房产类型、户型、价格区间、面积范围等筛选条件，返回分页房源列表；支持按价格、面积、发布时间、热度多维度排序，单页最多返回 50 条数据，满足多样化检索需求。
- 房天下数据特性
- 权威合规：数据源自房天下官方房产数据库，符合住建部房产信息公示规范，商用场景需遵守平台数据协议；
- 筛选维度丰富：支持 15 + 筛选条件组合，涵盖区域多级筛选（省 / 市 / 区 / 街道）、房产类型（新房 / 二手房 / 租房 / 商铺）、户型（一居至五居 + 别墅）、价格区间、面积范围、装修状态、配套设施（学区 / 地铁 / 医院）等；
- 实时性强：二手房挂牌价、租房状态等动态数据 10 分钟内同步，新房开盘信息实时更新；
- 权限分级管控：基础房源列表开放度高，业主联系方式、精准成交记录等敏感数据需企业资质授权。
- 典型应用场景
- 房产搜索平台搭建：整合多维度筛选功能，为用户提供一站式房源检索服务；
- 购房需求匹配工具：根据用户输入的关键词和筛选条件，自动推送符合要求的房源列表；
- 房产市场行情监控：定时检索特定区域 / 品类房源，统计价格走势、供需变化，辅助投资决策；
- 房产中介获客系统：批量获取目标区域房源列表，生成潜在客户开发清单。
2. 核心参数与返回字段
（1）请求参数（GET/POST 提交，需签名认证）
| 参数类型 | 参数名称 | 类型 | 是否必填 | 说明 | 应用示例 |
|---|---|---|---|---|---|
| 公共参数 | key | string | 是 | 调用 key（开放平台获取） | fang_api_89abcdef |
| secret | string | 是 | 调用密钥（开放平台获取） | fang_secret_12345678 | |
| api_name | string | 是 | 接口名称，固定为item_search | fang.item.search | |
| result_type | string | 否 | 响应格式，默认 JSON | json/xml | |
| cache | string | 否 | 是否启用缓存，默认 yes | yes/no | |
| 业务参数 | q | string | 是 | 搜索关键词，需 URL 编码 | 北京朝阳 三居室 地铁房 |
| region | string | 否 | 区域编码（多级用,分隔，从开放平台获取编码表） | 110000,110105（北京 - 朝阳） | |
| house_type | string | 否 | 房产类型 | new（新房）/second（二手房）/rent（租房）/commercial（商业） | |
| house_style | string | 否 | 户型编码 | 3room（三居室）/2room（两居室）/villa（别墅） | |
| price_min | float | 否 | 最低价格（新房 / 二手房为总价万元，租房为月租元） | 500 | |
| price_max | float | 否 | 最高价格 | 1000 | |
| area_min | float | 否 | 最低面积（㎡） | 100 | |
| area_max | float | 否 | 最高面积 | 150 | |
| decoration | string | 否 | 装修状态 | full（精装）/half（简装）/none（毛坯） | |
| support | string | 否 | 配套设施 | metro（地铁房）/school（学区房）/hospital（近医院） | |
| sort_type | string | 否 | 排序方式，默认publish_time_desc | price_asc（价格升序）/area_desc（面积降序）/hot_desc（热度降序） | |
| page_num | int | 否 | 页码，默认 1 | 1 | |
| page_size | int | 否 | 单页条数，默认 20，最大 50 | 50 |
注意事项
region必须使用开放平台提供的标准区域编码，禁止直接传入区域名称（如 “北京朝阳”），否则筛选无效；price_min/price_max的单位随house_type变化，需在代码中做适配处理；- 签名生成需包含所有非空参数，按参数名 ASCII 升序排序后拼接 secret 进行 MD5 加密，缺一不可。
（2）返回核心字段（按业务分类）
| 字段分类 | 核心字段 | 说明 |
|---|---|---|
| 基础房源信息 | house_id | 房源唯一 ID（用于调用 item_get 接口） |
| house_name | 房源名称（如 “XX 小区 3 室 2 厅”） | |
| building_name | 所属楼盘名称 | |
| region | 所属区域（省 / 市 / 区） | |
| house_type | 房产类型 | |
| house_style | 户型 | |
| 价格与面积信息 | price | 价格（新房 / 二手房为总价万元，租房为月租元） |
| unit_price | 单价（元 /㎡，仅新房 / 二手房返回） | |
| area | 建筑面积（㎡） | |
| 关键属性信息 | decoration | 装修状态 |
| support | 配套设施标签（如 ["地铁房","学区房"]） | |
| publish_time | 房源发布时间 | |
| transaction_status | 交易状态（在售 / 出租中） | |
| 分页信息 | total | 搜索结果总数 |
| page_num | 当前页码 | |
| page_size | 单页条数 | |
| has_next | 是否有下一页（true/false） |
提示：
item_search仅返回房源基础信息，户型图、实景图、详细配套等需调用item_get接口获取。
3. 接口限制与注意事项
| 权限类型 | 日调用上限 | 调用频率 | 适用场景 |
|---|---|---|---|
| 个人测试权限 | 100 次 / 天 | 2 次 / 秒 | 功能调试、个人房产查询 |
| 企业基础权限 | 1000 次 / 天 | 5 次 / 秒 | 中小型房产中介、个人建站 |
| 企业高级权限 | 10000 次 / 天 | 20 次 / 秒 | 大型房产平台、数据服务商、行业研究机构 |
- 数据缓存规则：基础房源列表缓存 30 分钟，价格、状态等动态数据缓存 10 分钟；
- 内容限制：违规房源、已下架房源不返回数据，敏感数据需单独申请权限；
- 合规要求：数据仅用于合规房产信息展示、市场分析，严禁转售、篡改或用于炒房等违规用途；
- 地域限制：部分城市的房产数据受当地监管政策限制，仅对本地企业开放。
二、对接前准备：权限与环境搭建
1. 获取接口权限（官方唯一合规路径）
房天下item_search接口由房天下开放平台提供，接入步骤如下：
- 登录房天下开放平台（https://open1.fang.com），注册企业 / 个人开发者账号；
- 提交资质审核：企业上传营业执照、房产中介备案证书（如有）；个人上传身份证，填写应用用途（如 “房产搜索工具”）；
- 创建应用，填写应用名称、服务器 IP 白名单、数据用途说明，提交审核；
- 审核通过后，获取
key和secret（接口调用核心凭证），配置服务器 IP 白名单； - 申请
fang.item.search接口权限，根据业务需求选择权限等级（基础 / 进阶 / 高级）。
风险提示：严禁使用非合规爬虫、第三方代理接口抓取数据，违反平台协议会导致账号封禁、法律追责。
2. 技术环境准备
（1）支持语言与协议
- 协议：HTTPS（强制，HTTP 请求会被直接拦截）；
- 开发语言：Python、Java、PHP、Go 等主流语言，推荐 Python（适配签名生成、异步并发与数据解析）。
（2）必备工具与依赖
| 工具类型 | 推荐工具 | 用途 |
|---|---|---|
| 调试工具 | 房天下开放平台调试工具 | 自动生成签名，验证参数与响应结果 |
| Postman | 模拟 GET/POST 请求，排查代码逻辑问题 | |
| 区域编码查询工具 | 获取标准区域编码，避免筛选错误 | |
| 开发依赖 | requests | 发送 HTTPS 请求 |
| hashlib | 生成 MD5 签名，确保接口安全 | |
| jsonpath-ng | 快速解析嵌套 JSON 响应数据 | |
| pandas | 批量整理房源列表数据，生成 Excel 报告 | |
| 辅助工具 | Redis | 缓存搜索结果，减少接口调用次数 |
| logging | 记录接口调用日志，便于审计与问题追溯 |
三、实操步骤：接口对接全流程（Python 示例）
步骤 1：理解签名认证规则（核心，必掌握）
房天下接口采用key+secret 签名认证机制，签名生成步骤如下：
- 收集所有非空请求参数（含公共参数与业务参数）；
- 按参数名ASCII 升序排序；
- 拼接参数为
key1value1key2value2...的字符串格式； - 将
secret拼接在参数串末尾，生成签名原串； - 对原串进行MD5 加密，转为小写字符串，即为签名
sign； - 将
sign添加到请求参数中，发送 HTTPS 请求。
步骤 2：完整代码实现（含签名生成 + 调用 + 数据标准化）
（1）依赖安装
bash
运行
pip install requests hashlib jsonpath-ng pandas（2）Python 代码实现
import requests import hashlib import time import logging import pandas as pd from urllib.parse import quote # 封装好API供应商demo url=https://console.open.onebound.cn/console/?i=Lex # 日志配置：记录调用日志，便于问题排查 logging.basicConfig( level=logging.INFO, format="%(asctime)s - %(levelname)s - %(message)s", handlers=[logging.FileHandler("fang_item_search.log"), logging.StreamHandler()] ) # 配置信息（替换为你的开放平台信息） CONFIG = { "key": "你的接口key", "secret": "你的接口secret", "api_url": "https://api.fang.com/fang/item_search", "result_type": "json", "cache": "yes" } def generate_sign(params: dict, secret: str) -> str: """生成房天下接口签名（MD5加密）""" # 1. 按参数名ASCII升序排序 sorted_params = sorted(params.items(), key=lambda x: x[0]) # 2. 拼接参数为key1value1key2value2格式 param_str = "".join([f"{k}{v}" for k, v in sorted_params]) # 3. 拼接secret并MD5加密 sign_str = param_str + secret sign = hashlib.md5(sign_str.encode("utf-8")).hexdigest().lower() return sign def standardize_house_list_data(raw_house: dict) -> dict: """标准化房源列表数据，统一输出格式""" # 处理配套设施标签 support_tags = raw_house.get("support", []) support_str = ",".join(support_tags) if isinstance(support_tags, list) else support_tags return { "房源ID": raw_house.get("house_id", ""), "房源名称": raw_house.get("house_name", ""), "所属楼盘": raw_house.get("building_name", ""), "所属区域": raw_house.get("region", ""), "房产类型": raw_house.get("house_type", ""), "户型": raw_house.get("house_style", ""), "价格": raw_house.get("price", 0.0), "单价(元/㎡)": raw_house.get("unit_price", 0.0), "建筑面积(㎡)": raw_house.get("area", 0.0), "装修状态": raw_house.get("decoration", ""), "配套设施": support_str, "发布时间": raw_house.get("publish_time", ""), "交易状态": raw_house.get("transaction_status", ""), "请求时间": time.strftime("%Y-%m-%d %H:%M:%S", time.localtime()) } def fang_item_search( keyword: str, region: str = None, house_type: str = None, house_style: str = None, price_min: float = None, price_max: float = None, area_min: float = None, area_max: float = None, decoration: str = None, support: str = None, sort_type: str = "publish_time_desc", page_num: int = 1, page_size: int = 20 ) -> dict: """调用房天下item_search接口获取房源列表""" # 1. 校验必填参数 if not keyword: return {"success": False, "error_msg": "关键词不能为空", "data": [], "pagination": {}} # 2. 构建公共参数 params = { "key": CONFIG["key"], "api_name": "item_search", "result_type": CONFIG["result_type"], "cache": CONFIG["cache"], "q": quote(keyword, encoding="utf-8"), "sort_type": sort_type, "page_num": page_num, "page_size": min(page_size, 50) # 单页最大50条 } # 3. 补充分筛参数 if region: params["region"] = region if house_type: params["house_type"] = house_type if house_style: params["house_style"] = house_style if price_min is not None: params["price_min"] = price_min if price_max is not None: params["price_max"] = price_max if area_min is not None: params["area_min"] = area_min if area_max is not None: params["area_max"] = area_max if decoration: params["decoration"] = decoration if support: params["support"] = support # 4. 生成签名 sign = generate_sign(params, CONFIG["secret"]) params["sign"] = sign try: # 5. 发送HTTPS请求 response = requests.get( url=CONFIG["api_url"], params=params, timeout=15, verify=True # 生产环境建议开启证书验证 ) response.raise_for_status() # 抛出HTTP状态码异常 result = response.json() # 6. 解析响应结果 if result.get("error_response"): error = result["error_response"] error_msg = f"{error.get('code', '未知错误')}: {error.get('msg', '无错误信息')}" logging.error(f"搜索失败（关键词：{keyword}）：{error_msg}") return {"success": False, "error_msg": error_msg, "data": [], "pagination": {}} search_result = result.get("item_search_response", {}).get("houses", {}) raw_houses = search_result.get("house", []) if not raw_houses: logging.warning(f"无匹配房源（关键词：{keyword}）") return {"success": False, "error_msg": "无匹配房源数据", "data": [], "pagination": {}} # 7. 标准化数据与分页信息 standard_houses = [standardize_house_list_data(house) for house in raw_houses] pagination = { "total": int(search_result.get("total", 0)), "page_num": page_num, "page_size": page_size, "has_next": search_result.get("has_next", False) } return { "success": True, "data": standard_houses, "pagination": pagination, "error_msg": "" } except requests.exceptions.RequestException as e: logging.error(f"网络请求异常（关键词：{keyword}）：{str(e)}") return {"success": False, "error_msg": f"网络异常：{str(e)}", "data": [], "pagination": {}} except Exception as e: logging.error(f"数据解析异常（关键词：{keyword}）：{str(e)}") return {"success": False, "error_msg": f"解析异常：{str(e)}", "data": [], "pagination": {}} # 封装好API供应商demo url=https://console.open.onebound.cn/console/?i=Lex # 调用示例 if __name__ == "__main__": # 搜索条件：北京朝阳 三居室 地铁房，二手房，总价500-1000万，面积100-150㎡ keyword = "北京朝阳 三居室 地铁房" region = "110000,110105" # 北京-朝阳区域编码 house_type = "second" price_min = 500.0 price_max = 1000.0 area_min = 100.0 area_max = 150.0 support = "metro" # 调用接口 result = fang_item_search( keyword=keyword, region=region, house_type=house_type, price_min=price_min, price_max=price_max, area_min=area_min, area_max=area_max, support=support, page_size=20 ) if result["success"]: print(f"搜索成功：共找到 {result['pagination']['total']} 套房源") for house in result["data"][:5]: # 打印前5条数据 print(f"房源ID：{house['房源ID']} | 名称：{house['房源名称']} | 价格：{house['价格']}万 | 配套：{house['配套设施']}") # 保存为Excel df = pd.DataFrame(result["data"]) df.to_excel(f"房天下房源列表_{keyword}.xlsx", index=False) # 翻页示例 if result["pagination"]["has_next"]: next_page_result = fang_item_search( keyword=keyword, region=region, house_type=house_type, price_min=price_min, price_max=price_max, area_min=area_min, area_max=area_max, support=support, page_num=2, page_size=20 ) print(f"下一页获取到 {len(next_page_result['data'])} 套房源") else: print(f"搜索失败：{result['error_msg']}")四、调试与问题排查：快速解决对接异常
1. 优先用官方工具调试（排除签名与参数问题）
登录房天下开放平台调试工具，选择 fang.item.search 接口；
输入关键词、区域编码、房产类型等参数，工具自动生成签名并发送请求；
若官方工具调用成功 → 问题出在代码的签名生成或参数拼接逻辑；
若官方工具调用失败 → 问题出在权限配置或参数有效性（如区域编码错误、权限不足）。
2. 高频问题排查表
问题现象 | 常见原因 | 解决方案 |
|---|---|---|
签名验证失败（401） | 1. key/secret 错误；2. 参数未按 ASCII 升序排序；3. cache 参数未加入签名；4. 关键词未 URL 编码 | 1. 核对开放平台应用的 key/secret；2. 严格按参数名 ASCII 升序排序所有非空参数；3. 将 cache 参数加入签名生成；4. 对关键词进行 URL 编码处理 |
权限不足（403） | 1. 未申请fang.item.search接口权限；2. 服务器 IP 不在白名单；3. 调用频率超限；4. 申请的权限等级不足 | 1. 在开放平台申请对应接口权限；2. 添加服务器 IP 到白名单；3. 降低调用频率，控制并发数≤权限上限；4. 升级权限等级，申请敏感数据访问权限 |
参数错误（400） | 1. 关键词为空；2. 区域编码格式错误（传入名称而非编码）；3. page_size>50；4. 价格 / 面积参数为负数 | 1. 确保 keyword 参数非空；2. 使用开放平台提供的标准区域编码；3. page_size 设置≤50；4. 价格 / 面积参数设置为≥0 的数值 |
无房源数据返回 | 1. 关键词无匹配；2. 筛选条件过严（如价格区间过小）；3. 房源受地域监管限制 | 1. 简化关键词，去掉冗余限制条件；2. 放宽筛选条件（如扩大价格区间、增加面积范围）；3. 联系开放平台客服确认地域权限 |
响应超时（504） | 1. 网络波动；2. page_size 过大（如 50 条）；3. 高峰期调用（工作日 9:00-11:00） | 1. 添加重试机制；2. 减小 page_size 至 20 条以内；3. 避开高峰期调用，增加超时时间至 15 秒 |
五、进阶优化：生产级稳定性提升
1. 性能与配额优化
批量翻页优化：通过 has_next 字段判断是否继续翻页，避免无效请求；多关键词 / 多区域查询时采用 异步并发（aiohttp），并发数≤权限允许的频率上限（如企业基础权限 5 次 / 秒）；
智能缓存策略：用 Redis 缓存搜索结果，缓存 key 为 fang_search_关键词_区域_房产类型_页码，动态数据（价格 / 状态）缓存 10 分钟，基础信息缓存 30 分钟，减少重复调用；
字段精简：仅保留业务必需字段（如房源 ID、名称、价格），避免返回冗余数据，提升响应速度。
2. 数据质量优化
数据去重：按 house_id 去重，避免同一房源重复出现在不同页码或不同关键词搜索结果中；
异常值过滤：过滤价格≤0、面积≤0 的房源，剔除交易状态为 “已售 / 已租” 的无效数据；
单位统一处理：针对不同房产类型的价格单位差异，在标准化函数中添加单位标注（如 “500 万（总价）”“3000 元（月租）”）。
3. 合规与安全优化
密钥管理：生产环境禁止硬编码 key 和 secret，存储在配置中心（如 Nacos、Apollo）或环境变量中；定期轮换密钥（每 3 个月一次），降低泄露风险；
重试机制：对 403（频率超限）、504（超时）等临时性错误，添加 指数退避重试 策略，首次重试间隔 1 秒，之后间隔翻倍，最多重试 3 次；对 400、401 等永久性错误直接抛出，不重试；
日志审计：记录每次调用的关键词、筛选条件、响应状态、数据条数，日志保留至少 30 天，满足合规审计要求。
六、扩展场景：接口联动与功能升级
联动 item_get 接口：通过 item_search 获取房源 ID 列表，批量调用 item_get 接口获取房源详情、户型图、配套设施等全量数据，实现 “搜索 - 详情” 全链路数据采集；
房产价格预警系统：定时调用 item_search 接口监控目标区域房源价格，当价格低于用户设定阈值时，通过邮件 / 短信自动推送提醒；
智能房源推荐系统：基于用户输入的关键词和筛选条件，结合房源详情数据，构建推荐算法，为用户推送个性化房源列表；
房产市场分析平台：聚合多维度搜索结果，统计不同区域、户型、价格段的房源供需情况，生成可视化分析报告，辅助行业研究与投资决策。
