?

接口概述

dp123電天下平臺 提供了 獲取電天下列表詳情數(shù)據(jù) 的 API 接口。該接口主要用于查詢平臺上的電天下相關(guān)數(shù)據(jù)列表及其詳情信息。開發(fā)者可以通過此接口獲取結(jié)構(gòu)化數(shù)據(jù)，用于數(shù)據(jù)分析、可視化展示或與其他系統(tǒng)集成。

接口基本信息

請求方式： GET

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

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

請求參數(shù)

調(diào)用此接口通常需要傳遞以下關(guān)鍵參數(shù)：

返回數(shù)據(jù)結(jié)構(gòu)

接口成功調(diào)用后，將返回 JSON 格式的數(shù)據(jù)。主要結(jié)構(gòu)如下：

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

code: 響應(yīng)狀態(tài)碼。0 通常表示成功，非 0 表示錯誤（具體錯誤碼需參考官方文檔）。

message: 響應(yīng)消息，成功時為 "success"，錯誤時包含錯誤信息。

data: 核心數(shù)據(jù)對象。

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

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

調(diào)用示例 (Python)

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

import requests

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

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

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

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

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

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

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

注意事項

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

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

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

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

數(shù)據(jù)解析： 根據(jù)返回數(shù)據(jù)中的 type 或其他字段，可能需要不同的邏輯來解析 list 中的詳情數(shù)據(jù)。詳情字段的結(jié)構(gòu)應(yīng)以官方文檔為準。

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

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

常見問題

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

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

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

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

請注意：

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

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

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

祝您開發(fā)順利！

?審核編輯 黃宇