?

摘要： 本文將介紹如何調用房天下（Fang.com）提供的 API 接口，實現根據指定關鍵詞（如樓盤名、區域、特色等）查詢并獲取房產列表數據的技術方案。這對于需要集成實時房產信息或進行市場分析的開發者非常有用。

一、 接口概述

房天下平臺為其合作伙伴或注冊開發者提供了數據接口服務，允許通過 HTTP 請求獲取其數據庫中的房產信息。其中，根據關鍵詞搜索房源列表是一個常用且核心的功能。

核心功能： 輸入一個關鍵詞（例如："海淀學區房"、"朝陽三居"、"萬科樓盤"），API 將返回與該關鍵詞匹配的房產列表數據。

數據內容： 返回的列表數據通常包含房源的基礎信息，如：樓盤名稱、所在區域、價格、戶型、面積、特色標簽、圖片鏈接、詳情頁 URL 等。

格式： 響應數據一般采用 JSON 格式，便于解析和處理。

二、 API 請求基礎信息（示例）

以下是一個典型的請求該接口所需的要素（請注意：實際接口地址、參數名和密鑰申請方式需參考房天下官方最新的開發者文檔）：

請求地址 (Endpoint):

GET https://api.fang.com/data/search/list

請求方法 (Method): GET

必要請求參數 (Query Parameters):

keyword: （必填） 搜索關鍵詞。用戶輸入的查詢字符串。

api_key: （必填） 開發者密鑰。需要在房天下開放平臺注冊申請。

city: （通常必填） 城市編碼或名稱。限定搜索范圍，如 bj 代表北京， sh 代表上海。

page: （可選）頁碼。用于分頁查詢，默認為 1。

pageSize: （可選）每頁返回的記錄數。默認為 10 或 20，具體看文檔說明。

可選請求參數： 根據接口設計，可能還支持更多篩選條件，如：

price_min, price_max: 價格區間。

area_min, area_max: 面積區間。

room: 居室數（如 2 代表兩居）。

... 等等。

三、 響應數據結構（示例）

一個成功的響應可能包含如下結構的 JSON 數據：

{
  "code": 200, // 狀態碼，200 表示成功
  "message": "success", // 狀態信息
  "data": {
    "total": 125, // 匹配關鍵詞的總記錄數
    "page": 1, // 當前頁碼
    "pageSize": 10, // 每頁數量
    "list": [ // 房源數據列表
      {
        "id": "123456789", // 房源唯一 ID
        "title": "海淀中關村學區房 三室一廳 南北通透", // 房源標題
        "city": "北京", // 城市
        "district": "海淀區", // 區域
        "price": "850", // 價格（單位通常是 萬 或 元/平米，需確認）
        "price_unit": "萬", // 價格單位
        "room": "3室1廳", // 戶型
        "area": "89.5", // 面積（平米）
        "tags": ["學區房", "地鐵房", "精裝修"], // 特色標簽
        "image_url": "https://img.fang.com/xxx.jpg", // 封面圖片 URL
        "detail_url": "https://www.fang.com/property/123456789.html" // 詳情頁 URL
      },
      // ... 更多房源數據項
    ]
  }
}

四、 調用示例 (Python)

以下是一個使用 Python 的 requests 庫調用該 API 的簡單示例代碼：

import requests

# 替換為你在房天下開放平臺申請的 API Key
API_KEY = "YOUR_API_KEY_HERE"
# 替換為實際的目標城市編碼
CITY_CODE = "bj"
# 你的搜索關鍵詞
KEYWORD = "學區房"
# 目標頁碼
PAGE = 1
# 每頁數量
PAGE_SIZE = 10

# 構造請求 URL 和參數
url = "https://api.fang.com/data/search/list"
params = {
    "api_key": API_KEY,
    "city": CITY_CODE,
    "keyword": KEYWORD,
    "page": PAGE,
    "pageSize": PAGE_SIZE
}

try:
    # 發送 GET 請求
    response = requests.get(url, params=params)
    response.raise_for_status()  # 檢查請求是否成功

    # 解析 JSON 響應
    data = response.json()

    # 檢查 API 返回狀態
    if data.get('code') == 200:
        # 獲取房源列表
        property_list = data['data']['list']
        total_properties = data['data']['total']
        print(f"找到 {total_properties} 條相關房源。當前頁結果：")
        for prop in property_list:
            print(f"標題: {prop['title']}")
            print(f"區域: {prop['district']}")
            print(f"價格: {prop['price']}{prop.get('price_unit', '')}")
            print(f"戶型面積: {prop['room']} {prop['area']}㎡")
            print(f"詳情頁: {prop['detail_url']}")
            print("-" * 50)
    else:
        print(f"API 調用失敗: {data.get('message')}")

except requests.exceptions.RequestException as e:
    print(f"網絡請求出錯: {e}")
except ValueError as e:
    print(f"JSON 解析出錯: {e}")

代碼說明：

導入庫： 使用 requests 庫發送 HTTP 請求。

配置參數： 設置必要的參數：api_key, city, keyword, page, pageSize。

發送請求： 使用 requests.get() 方法發送 GET 請求。

錯誤處理： 使用 try-except 捕獲網絡請求和 JSON 解析可能出現的異常。response.raise_for_status() 確保 HTTP 狀態碼指示成功。

解析響應： 將響應內容解析為 JSON 對象 (data)。

檢查狀態碼： 檢查 data['code'] 是否為 200 (成功)。

提取數據： 如果成功，從 data['data']['list'] 中遍歷獲取房源列表信息并打印。

安全提示： 切勿將真實的 API_KEY 硬編碼在代碼中或上傳至公開倉庫！ 應使用環境變量或安全的配置管理方式存儲密鑰。

五、 注意事項

官方文檔： 務必參考房天下官方提供的最新 API 文檔，了解確切的接口地址、參數列表、參數格式（例如 city 是名稱還是編碼）、數據字段含義、價格單位、分頁規則、調用頻率限制等。文檔是唯一權威來源。

API Key 安全： 保護你的 API Key 如同保護密碼。不要在客戶端代碼（如網頁前端、移動 App）中直接暴露 API Key，以防被他人濫用。通常應在服務器端進行 API 調用。

調用限制： 大多數開放 API 都有調用頻率限制（Rate Limit）。請遵守平臺規定，避免過于頻繁的請求導致接口被禁用。

錯誤處理： 在實際應用中，應完善對各種錯誤狀態碼（如 401 未授權， 403 禁止， 429 請求過多， 500 服務器錯誤）的處理邏輯。

數據解析： 響應數據的結構或字段名可能隨平臺更新而變化，解析代碼應具備一定的容錯性。

數據授權： 獲取的數據應僅用于授權范圍內的用途，遵守相關法律法規和平臺的使用協議。

六、 總結

通過調用房天下的關鍵詞搜索列表 API，開發者能夠便捷地集成實時、豐富的房產數據到自己的應用或分析流程中。關鍵在于仔細閱讀官方文檔、正確處理認證（API Key）、管理好調用頻率并安全地存儲密鑰。希望本文提供的思路和示例代碼能幫助你快速上手集成此功能。

如有任何疑問，歡迎大家留言探討。

?
sf