安家 GO item_area - 获取地区类列表数据接口对接全攻略：从入门到精通

一、接口核心认知：功能与适配场景

1. 接口定位与核心价值

• 核心功能：输入上级区域编码（如省编码），返回下级区域的层级化列表；支持无参数查询全国省级列表，也支持精准查询指定区域的子级商圈；返回数据包含区域唯一编码、名称、房源数量、是否支持筛选等属性，为后续房源搜索提供标准的区域筛选维度。

• 安家 GO 数据特性

• 层级标准化：严格遵循国家行政区划标准，同时补充房产业务专属的商圈维度（如 “XXCBD”“XX 学区商圈”），适配房产检索场景；

• 数据联动性：返回的区域编码可直接作为 item_search 接口的 region 参数值，避免因编码不匹配导致的筛选无效问题；

• 更新及时：行政区划调整、新商圈规划等数据实时同步，保障区域筛选的准确性；

• 权限无差别：基础区域列表数据对所有权限等级用户开放，无额外资质要求。

• 典型应用场景

1. 房产搜索平台的区域筛选组件：构建省→市→区→商圈的多级联动下拉菜单，供用户选择检索范围；

2. 房源数据的地域分类统计：按区域维度统计房源数量、价格分布，生成市场分析报表；

3. 中介获客的区域定向：根据区域列表选择目标商圈，批量获取该商圈内的房源数据；

4. 多城市房产平台的基础数据支撑：为全国多城市布局的平台提供统一的区域编码体系。

2. 核心参数与返回字段

（1）请求参数（GET/POST 提交，需签名认证）

注意事项

1. parent_id 为空时，默认返回全国省级行政区列表，这是所有区域查询的起点；

2. level 参数用于限制返回数据的层级，例如传入 parent_id=310000（上海）且 level=3，仅返回上海市下辖的区级数据（如浦东、徐汇）；

3. 签名生成需包含所有非空参数，按参数名 ASCII 升序排序后拼接secret进行 MD5 加密，参数缺失会导致签名验证失败。

（2）返回核心字段（按层级分类）

提示：sub_area 字段仅在未指定level参数时返回，用于构建多级区域树；若指定level，则仅返回当前层级数据，无下级嵌套。

3. 接口限制与注意事项

• 数据缓存规则：省级 / 市级数据缓存24 小时（行政区划变动频率低），区级 / 商圈数据缓存1 小时（房源数量实时变化）；

• 调用建议：区域数据变动频率低，建议本地缓存全量区域树，仅在行政区划调整时主动更新，减少接口调用次数；

• 合规要求：区域编码和名称数据可自由使用，但禁止篡改编码体系或用于非房产相关的商业场景；

• 特殊说明：部分新规划的商圈可能存在 is_valid=false 的情况，这类区域暂不支持作为 item_search 的筛选条件。

二、对接前准备：权限与环境搭建

1. 获取接口权限（官方唯一合规路径）

1. 登录安家 GO 开放平台（https://open.anjiago.com），注册企业 / 个人开发者账号；

2. 提交资质审核：

• 企业用户：上传营业执照、房产中介备案证书（如有）；

• 个人用户：上传身份证，填写应用用途（如 “房产区域筛选组件开发”）；

3. 创建应用，填写应用名称、服务器 IP 白名单、数据用途说明，提交审核；

4. 审核通过后，在 “应用管理 - 密钥管理” 中获取 key 和 secret（接口调用核心凭证）；

5. 申请 anjia.item.area 接口权限，该接口为基础接口，审核通过时间通常不超过 1 个工作日。

风险提示：严禁通过非官方渠道获取区域数据，非标准编码会导致后续房源搜索接口筛选失效。

2. 技术环境准备

（1）支持语言与协议

• 协议：HTTPS（强制），HTTP 请求会被直接拦截并返回 403 错误；

• 开发语言：Python、Java、PHP、Go 等主流语言均可，推荐 Python（代码简洁，适配层级数据解析）。

（2）必备工具与依赖

三、实操步骤：接口对接全流程（Python 示例）

步骤 1：理解签名认证规则（核心，必掌握）

1. 收集所有非空请求参数（含公共参数key/api_name等 + 业务参数parent_id/level等）；

2. 按参数名ASCII 升序排序（如api_name排在cache之前）；

3. 拼接参数为 key1value1key2value2... 的字符串格式（无分隔符，参数值需与传入一致）；

4. 将 secret 拼接在参数串末尾，生成签名原串；

5. 对原串进行 MD5 加密，转为小写字符串，即为签名 sign；

6. 将 sign 添加到请求参数中，发送 HTTPS GET 请求。

步骤 2：完整代码实现（含签名生成 + 多级查询 + 数据标准化）

（1）依赖安装

（2）Python 代码实现

import requests
import hashlib
import time
import logging
import pandas as pd
from typing import List, Dict, Optional
# 封装好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("anjia_item_area.log"), logging.StreamHandler()]
)

# 配置信息（替换为你的开放平台key/secret）
CONFIG = {
    "key": "你的接口key",
    "secret": "你的接口secret",
    "api_url": "https://api.anjiago.com/anjia/item_area",
    "result_type": "json",
    "cache": "yes"
}

def generate_sign(params: Dict[str, str], secret: str) -> str:
    """生成安家GO接口签名（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_area_data(raw_area: Dict) -> Dict:
    """标准化区域数据格式"""
    return {
        "区域编码": raw_area.get("area_id", ""),
        "区域名称": raw_area.get("area_name", ""),
        "上级编码": raw_area.get("parent_id", ""),
        "区域层级": raw_area.get("level", 0),
        "房源数量": raw_area.get("house_count", 0),
        "是否支持筛选": raw_area.get("is_valid", False),
        "请求时间": time.strftime("%Y-%m-%d %H:%M:%S", time.localtime())
    }

def anjia_item_area(
    parent_id: Optional[str] = None,
    level: Optional[int] = None
) -> Dict:
    """
    调用安家GO item_area接口获取区域列表
    :param parent_id: 上级区域编码，不传返回省级列表
    :param level: 查询层级，不传返回下级全量层级
    :return: 标准化的区域列表及接口调用状态
    """
    # 1. 构建公共参数
    params = {
        "key": CONFIG["key"],
        "api_name": "item_area",
        "result_type": CONFIG["result_type"],
        "cache": CONFIG["cache"]
    }

    # 2. 添加工业务参数
    if parent_id is not None:
        params["parent_id"] = parent_id
    if level is not None:
        params["level"] = str(level)  # 确保参数为字符串类型

    # 3. 生成签名
    sign = generate_sign(params, CONFIG["secret"])
    params["sign"] = sign

    try:
        # 4. 发送HTTPS请求
        response = requests.get(
            url=CONFIG["api_url"],
            params=params,
            timeout=10,
            verify=True  # 生产环境必须开启证书验证
        )
        response.raise_for_status()
        result = response.json()

        # 5. 解析响应结果
        if result.get("error_response"):
            error = result["error_response"]
            error_msg = f"[{error.get('code', '未知错误')}] {error.get('msg', '无错误信息')}"
            logging.error(f"获取区域列表失败：{error_msg}")
            return {"success": False, "error_msg": error_msg, "data": []}

        raw_area_list = result.get("item_area_response", {}).get("area_list", [])
        if not raw_area_list:
            logging.warning("未返回任何区域数据")
            return {"success": False, "error_msg": "无区域数据返回", "data": []}

        # 6. 标准化数据（递归处理子区域，若存在）
        def recursive_standardize(area_list: List[Dict]) -> List[Dict]:
            standard_list = []
            for area in area_list:
                std_area = standardize_area_data(area)
                # 处理子区域
                if "sub_area" in area and area["sub_area"]:
                    std_area["子区域列表"] = recursive_standardize(area["sub_area"])
                standard_list.append(std_area)
            return standard_list

        standard_data = recursive_standardize(raw_area_list)
        return {"success": True, "error_msg": "", "data": standard_data}

    except requests.exceptions.RequestException as e:
        logging.error(f"网络请求异常：{str(e)}")
        return {"success": False, "error_msg": f"网络异常：{str(e)}", "data": []}
    except Exception as e:
        logging.error(f"数据解析异常：{str(e)}")
        return {"success": False, "error_msg": f"解析异常：{str(e)}", "data": []}
# 封装好API供应商demo url=https://console.open.onebound.cn/console/?i=Lex
# 调用示例
if __name__ == "__main__":
    # 示例1：查询全国省级列表
    print("=== 查询全国省级列表 ===")
    province_result = anjia_item_area()
    if province_result["success"]:
        for province in province_result["data"][:5]:  # 打印前5个省份
            print(f"{province['区域编码']} | {province['区域名称']} | 房源数：{province['房源数量']}")
        # 保存为Excel
        df_province = pd.DataFrame(province_result["data"])
        df_province.to_excel("安家GO全国省级区域列表.xlsx", index=False)

    # 示例2：查询上海市下属区级列表（parent_id=310000，level=3）
    print("\n=== 查询上海市下属区级列表 ===")
    shanghai_district_result = anjia_item_area(parent_id="310000", level=3)
    if shanghai_district_result["success"]:
        for district in shanghai_district_result["data"]:
            print(f"{district['区域编码']} | {district['区域名称']} | 房源数：{district['房源数量']}")
        df_district = pd.DataFrame(shanghai_district_result["data"])
        df_district.to_excel("安家GO上海区级区域列表.xlsx", index=False)

    # 示例3：查询上海市浦东新区下属商圈列表（parent_id=310115，level=5）
    # print("\n=== 查询上海浦东商圈列表 ===")
    # pudong_business_result = anjia_item_area(parent_id="310115", level=5)
    # if pudong_business_result["success"]:
    #     for business in pudong_business_result["data"]:
    #         print(f"{business['区域编码']} | {business['区域名称']} | 房源数：{business['房源数量']}")

四、调试与问题排查：快速解决对接异常

1. 优先用官方工具调试（排除签名与参数问题）

1. 登录安家 GO 开放平台调试工具，选择 anjia.item.area 接口；

2. 输入parent_id和level参数（或留空查省级列表），点击 “生成签名” 并发送请求；

3. 若官方工具调用成功 → 问题出在代码的签名生成逻辑或参数类型错误（如level传整数而非字符串）；

4. 若官方工具调用失败 → 问题出在权限配置或参数有效性（如parent_id传入错误编码）。

2. 高频问题排查表

五、进阶优化：生产级稳定性提升

1. 性能与缓存优化

• 全量区域树本地缓存：首次调用接口获取全国省级列表，再递归获取所有下级区域，将完整的区域树缓存到 Redis / 本地数据库中，缓存有效期：省级 / 市级 24 小时，区级 / 商圈 1 小时；后续业务直接读取本地缓存，无需频繁调用接口；

• 按需查询层级：前端筛选组件仅需展示到区级时，直接调用level=3的接口，避免返回冗余的商圈数据，减少响应体积；

• 批量查询优化：若需获取多个城市的区域数据，采用异步并发调用（aiohttp），并发数控制在权限允许的频率上限内（如企业基础权限 10 次 / 秒）。

2. 数据质量优化

• 编码有效性校验：本地缓存的区域数据中，过滤掉is_valid=false的区域，避免前端展示不可筛选的区域选项；

• 层级关系校验：定期对比本地缓存的parent_id与接口返回数据，确保区域层级关系无误；

• 缺失值填充：对house_count为 0 的区域标注 “暂无房源”，提升用户体验。

3. 合规与安全优化

• 密钥管理：生产环境禁止硬编码key和secret，推荐存储在配置中心（如 Nacos）或环境变量中，通过os.environ读取；

• 日志审计：记录每次区域查询的parent_id、level、响应状态，日志保留至少 7 天，便于排查数据同步问题；

• 异常降级策略：当接口调用失败时，降级使用本地缓存的历史区域数据，保障业务不中断。

六、扩展场景：接口联动与业务落地

1. 多级联动筛选组件开发：基于item_area接口返回的层级数据，开发前端省→市→区→商圈的联动下拉菜单，选择后将area_id传入item_search接口，实现精准区域房源搜索；

2. 区域房源热力图：按house_count字段统计各区域房源数量，生成可视化热力图，直观展示房源分布情况；

3. 多城市平台的区域初始化：新上线城市时，调用item_area接口获取该城市的全量区域数据，批量初始化到本地数据库，为后续房源数据接入做准备；

4. 行政区划变动监控：定时调用接口对比本地缓存的区域编码和名称，当发现新增 / 变更区域时，自动触发更新流程。