?

接口概述

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

接口基本信息

請(qǐng)求方式： GET

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

認(rèn)證方式： API Key 認(rèn)證（通常需要在請(qǐng)求頭 Authorization 中傳遞）

請(qǐng)求參數(shù)

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

返回?cái)?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, // 總頁(yè)數(shù)
    "current_page": 1, // 當(dāng)前頁(yè)碼
    "page_size": 10, // 當(dāng)前頁(yè)數(shù)據(jù)條數(shù)
    "list": [
      {
        "id": "EW202405160001", // 電天下唯一ID
        "name": "某區(qū)域電網(wǎng)負(fù)荷數(shù)據(jù)", // 名稱(chēng)
        "type": "load", // 類(lèi)型 (例如：load-負(fù)荷, generation-發(fā)電, price-電價(jià))
        "region": "華東", // 所屬區(qū)域
        "description": "描述信息...", // 描述
        "create_time": 1715840000, // 創(chuàng)建時(shí)間 (Unix 時(shí)間戳)
        "update_time": 1715840000, // 更新時(shí)間 (Unix 時(shí)間戳)
        // ... 其他電天下特有的詳情字段，例如：peak_load, avg_price 等，具體取決于數(shù)據(jù)類(lèi)型
      },
      // ... 更多數(shù)據(jù)項(xiàng)
    ]
  }
}

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

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

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

total_count, total_pages, current_page, page_size: 分頁(yè)信息。

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

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

以下是一個(gè)使用 Python requests 庫(kù)調(diào)用該接口的簡(jiǎn)單示例：

import requests

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

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

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

try:
    # 發(fā)送 GET 請(qǐng)求
    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("請(qǐng)求成功!")
        print(f"總數(shù)據(jù)量: {data['data']['total_count']}")
        print(f"當(dāng)前頁(yè)數(shù)據(jù):")
        for item in data["data"]["list"]:
            print(f"- ID: {item['id']}, 名稱(chēng): {item['name']}, 類(lèi)型: {item['type']}, 區(qū)域: {item['region']}")
            # 打印其他你需要的詳情字段
    else:
        print(f"接口返回錯(cuò)誤: code={data['code']}, message={data['message']}")

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

注意事項(xiàng)

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

頻率限制： 平臺(tái)通常會(huì)對(duì) API 調(diào)用頻率進(jìn)行限制。請(qǐng)查閱官方文檔了解具體的限流策略，并在代碼中做好錯(cuò)誤重試或降級(jí)處理。

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

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

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

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

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

常見(jiàn)問(wèn)題

Q：返回 code=401 錯(cuò)誤？ A：通常表示認(rèn)證失敗。請(qǐng)檢查 api_key 是否正確，以及 Authorization 請(qǐng)求頭的格式是否符合平臺(tái)要求。

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

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

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

請(qǐng)注意：

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

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

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

祝您開(kāi)發(fā)順利！

?審核編輯 黃宇