安家 GO item_area 接口（官方标准命名 anjia.item.area）是获取房产相关行政区域 / 商圈列表的核心基础接口，支持多级区域（省→市→区→街道→商圈）的层级化查询，返回数据包含区域编码、名称、覆盖房源数量等核心字段，是调用 item_search/item_get 接口的前置依赖接口（需用该接口返回的标准区域编码作为筛选参数）。该接口采用 HTTPS+API Key/Secret 签名认证，支持 JSON/XML 双格式返回，具备数据标准化、层级清晰、更新及时的特点。本攻略从接口认知、权限准备、实操对接、调试排错到生产级优化，提供全链路标准化指导。

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

1. 接口定位与核心价值

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

   安家 GO 数据特性

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

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

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

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

   典型应用场景

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

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

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

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

2. 核心参数与返回字段

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

   参数类型 参数名称 类型 是否必填 说明 应用示例

   公共参数 key string 是 调用密钥（开放平台获取） anjia_api_2026_abc123

   secret string 是 调用秘钥（开放平台获取） anjia_secret_2026_def456

   api_name string 是 接口名称，固定为item_area anjia.item.area

   result_type string 否 响应格式，默认 JSON json/xml

   cache string 否 是否启用缓存，默认 yes yes/no

   业务参数 parent_id string 否 上级区域编码，不传则返回省级列表 空（查全国省）/310000（查上海下属区域）

   level int 否 查询层级（1 = 省，2 = 市，3 = 区，4 = 街道，5 = 商圈），不传则返回下级全量层级 3（仅返回区级数据）

   注意事项

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

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

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

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

   字段名称 类型 说明 示例

   area_id string 区域唯一编码（核心，用于后续接口调用） 310115（上海浦东）

   area_name string 区域名称 浦东新区

   parent_id string 上级区域编码 310000

   level int 当前区域层级 3（区级）

   house_count int 该区域内的房源总数（实时统计） 12580

   is_valid bool 是否支持作为筛选条件（true = 支持） true

   sub_area array 下级区域列表（仅当level不传时返回）

   {"area_id":"310115001","area_name":"张江商圈"...}

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

3. 接口限制与注意事项

   权限类型 日调用上限 调用频率 适用场景

   个人测试权限 200 次 / 天 5 次 / 秒 功能调试、区域列表展示

   企业基础权限 2000 次 / 天 10 次 / 秒 中小型房产平台、中介系统

   企业高级权限 无上限 20 次 / 秒 大型房产数据服务商、全国性平台

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

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

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

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

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

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

   安家 GO item_area 接口的权限获取流程与同平台其他接口一致，步骤如下：

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

   提交资质审核：

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

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

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

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

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

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

5. 技术环境准备

   （1）支持语言与协议

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

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

   （2）必备工具与依赖

   工具类型 推荐工具 用途

   调试工具 安家 GO 开放平台调试工具 在线输入parent_id和level，生成签名并测试接口响应

   Postman 模拟 GET/POST 请求，保存多级区域查询的测试用例

   开发依赖（Python） requests 发送 HTTPS 请求

   hashlib 生成 MD5 签名

   jsonpath-ng 解析嵌套的区域层级数据

   pandas 整理区域列表数据并导出 Excel

   辅助工具 Redis 缓存全量区域树数据，减少重复调用

   logging 记录接口调用日志，便于问题排查

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

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

   安家 GO 所有接口采用统一的 key+secret 签名认证 机制，item_area 接口的签名生成步骤如下：

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

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

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

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

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

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

   步骤 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 typing import List, Dict, Optional

日志配置

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, 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 = None,

level: Optional = 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": []}

调用示例

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. 优先用官方工具调试（排除签名与参数问题）

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

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

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

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

2. 高频问题排查表

   问题现象 常见原因 解决方案

   签名验证失败（401） 1. key/secret 错误或过期；

3. 参数未按 ASCII 升序排序；
4. level参数传整数而非字符串；
5. 缺失cache等公共参数 1. 核对开放平台的 key/secret，过期则重新申请；
6. 严格按参数名 ASCII 升序排序所有非空参数；
7. 将level等数值型参数转为字符串后再拼接；
8. 确保公共参数（key/api_name 等）全部传入

   权限不足（403） 1. 未申请anjia.item.area接口权限；

9. 服务器 IP 不在白名单 1. 在开放平台 “权限管理” 中申请该接口；
10. 添加服务器公网 IP 到应用白名单

    参数错误（400） 1. parent_id传入非法编码（如非平台标准编码）；

11. level传入超出范围的值（如 6，最大为 5） 1. 使用官方工具查询的有效编码作为parent_id；
12. level参数限制在 1-5 之间

    无数据返回（200 但 data 为空） 1. parent_id正确但无下级区域（如部分县级市无街道层级）；

13. 新区域未同步到接口 1. 核对parent_id对应的区域是否存在下级层级；
14. 联系开放平台客服同步最新区域数据

    响应超时（504） 1. 网络波动；

15. 未指定level，查询层级过深导致数据量过大 1. 添加重试机制，设置超时时间为 10 秒；
16. 指定level参数，限制返回数据的层级和体积

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

17. 性能与缓存优化

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

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

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

18. 数据质量优化

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

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

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

19. 合规与安全优化

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

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

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

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

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

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

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

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