?

接口概述

dp123電天下平臺 提供了 獲取電天下列表詳情數據 的 API 接口。該接口主要用于查詢平臺上的電天下相關數據列表及其詳情信息。開發者可以通過此接口獲取結構化數據，用于數據分析、可視化展示或與其他系統集成。

接口基本信息

請求方式： GET

接口地址： https://api.dp123.com/v1/electric-world/list-details (此為示例地址，實際地址請參考官方文檔)

認證方式： API Key 認證（通常需要在請求頭 Authorization 中傳遞）

請求參數

調用此接口通常需要傳遞以下關鍵參數：

返回數據結構

接口成功調用后，將返回 JSON 格式的數據。主要結構如下：

{
  "code": 0,
  "message": "success",
  "data": {
    "total_count": 100, // 符合條件的數據總條數
    "total_pages": 10, // 總頁數
    "current_page": 1, // 當前頁碼
    "page_size": 10, // 當前頁數據條數
    "list": [
      {
        "id": "EW202405160001", // 電天下唯一ID
        "name": "某區域電網負荷數據", // 名稱
        "type": "load", // 類型 (例如：load-負荷, generation-發電, price-電價)
        "region": "華東", // 所屬區域
        "description": "描述信息...", // 描述
        "create_time": 1715840000, // 創建時間 (Unix 時間戳)
        "update_time": 1715840000, // 更新時間 (Unix 時間戳)
        // ... 其他電天下特有的詳情字段，例如：peak_load, avg_price 等，具體取決于數據類型
      },
      // ... 更多數據項
    ]
  }
}

code: 響應狀態碼。0 通常表示成功，非 0 表示錯誤（具體錯誤碼需參考官方文檔）。

message: 響應消息，成功時為 "success"，錯誤時包含錯誤信息。

data: 核心數據對象。

total_count, total_pages, current_page, page_size: 分頁信息。

list: 數組，包含當前頁的電天下數據詳情對象列表。每個對象包含該條數據的基本信息和具體數值。

調用示例 (Python)

以下是一個使用 Python requests 庫調用該接口的簡單示例：

import requests

# 替換為你的實際 API Key 和接口地址
API_KEY = "YOUR_API_KEY_HERE"
API_URL = "https://api.dp123.com/v1/electric-world/list-details"

# 設置請求參數
params = {
    "api_key": API_KEY,
    "page": 1,
    "page_size": 5,
    "sort_field": "create_time",
    "sort_order": "desc"
}

# 添加 Authorization 頭部 (根據平臺要求，可能需要 Bearer Token 等形式)
headers = {
    "Authorization": f"Bearer {API_KEY}"  # 或者 "APIKEY {API_KEY}"，具體格式看平臺要求
}

try:
    # 發送 GET 請求
    response = requests.get(API_URL, params=params, headers=headers)
    response.raise_for_status()  # 如果響應狀態碼不是 200，將拋出異常

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

    if data["code"] == 0:
        print("請求成功!")
        print(f"總數據量: {data['data']['total_count']}")
        print(f"當前頁數據:")
        for item in data["data"]["list"]:
            print(f"- ID: {item['id']}, 名稱: {item['name']}, 類型: {item['type']}, 區域: {item['region']}")
            # 打印其他你需要的詳情字段
    else:
        print(f"接口返回錯誤: code={data['code']}, message={data['message']}")

except requests.exceptions.RequestException as e:
    print(f"請求發生錯誤: {e}")
except ValueError as e:
    print(f"解析 JSON 響應失敗: {e}")

注意事項

API Key 安全： API Key 是訪問憑證，務必妥善保管，不要在客戶端代碼或公共倉庫中暴露。建議將其存儲在環境變量或安全的配置管理服務中。

頻率限制： 平臺通常會對 API 調用頻率進行限制。請查閱官方文檔了解具體的限流策略，并在代碼中做好錯誤重試或降級處理。

參數驗證： 在調用前，確保傳遞的參數是有效的（例如，page_size 不超過最大值，filter_value 是平臺支持的合法值）。

錯誤處理： 代碼中應包含完善的錯誤處理邏輯，處理網絡錯誤、API 響應錯誤 ($code neq 0$) 以及 JSON 解析錯誤。

數據解析： 根據返回數據中的 type 或其他字段，可能需要不同的邏輯來解析 list 中的詳情數據。詳情字段的結構應以官方文檔為準。

時間戳處理： create_time, update_time 等通常是 Unix 時間戳（秒級或毫秒級），需要根據需要進行轉換（例如，使用 datetime 模塊）。

查閱文檔： 以上信息是基于常見 API 設計的推測。務必參考 dp123電天下平臺 提供的官方 API 文檔 以獲取最準確、最新的接口地址、參數、認證方式、返回字段定義和錯誤碼說明。

常見問題

Q：返回 code=401 錯誤？ A：通常表示認證失敗。請檢查 api_key 是否正確，以及 Authorization 請求頭的格式是否符合平臺要求。

Q：返回 code=400 錯誤？ A：通常表示請求參數錯誤。檢查傳遞的參數名是否正確，參數值是否在允許范圍內（例如，page_size 是否過大）。

Q：如何獲取更多詳情？ A：調用此接口獲取列表后，如果平臺提供了單獨的“獲取單條電天下詳情”接口，可以使用 list 中返回的 id 去請求該接口獲取更豐富的信息。

希望這篇指南能幫助你順利集成 dp123電天下平臺 的 API 接口！如有疑問，建議優先查閱官方文檔或聯系平臺技術支持。

請注意：

以上內容中的接口地址 (https://api.dp123.com/v1/electric-world/list-details)、參數名稱 (filter_field, filter_value 等)、返回字段名稱 (id, type, region 等) 均為示例。實際開發中，必須以 dp123電天下平臺 官方提供的 API 文檔為準。

API Key 的傳遞方式（是放在 URL 參數 api_key 中，還是放在 Authorization 請求頭中，以及請求頭的具體格式）需要根據平臺的具體要求來確定。

返回數據中的 list 數組里每個對象的詳細字段（如 peak_load, avg_price）會因具體的數據類型 (type) 而異，需要根據平臺定義的數據模型來解析。

祝您開發順利！

?審核編輯 黃宇