调用 dp123电天下平台 “获取电天下列表详情数据” API 接口指南

​

接口概述

dp123电天下平台 提供了 获取电天下列表详情数据 的 API 接口。该接口主要用于查询平台上的电天下相关数据列表及其详情信息。开发者可以通过此接口获取结构化数据，用于数据分析、可视化展示或与其他系统集成。

接口基本信息

请求方式： GET

接口地址： https://api.dp123.com/v1/electric-world/list-details (此为示例地址，实际地址请参考官方文档)

认证方式： API Key 认证（通常需要在请求头 Authorization 中传递）

请求参数

调用此接口通常需要传递以下关键参数：

参数名	类型	是否必填	说明
api_key	String	是	平台颁发的用于身份验证的密钥。
page	Integer	否	当前页码，用于分页查询。默认为 $1$。
page_size	Integer	否	每页数据条数，用于分页查询。默认为 $10$，最大值可能有限制（如 $100$）。
filter_field	String	否	筛选字段名（例如：region, type）。
filter_value	String	否	对应筛选字段的值。
sort_field	String	否	排序字段名（例如：create_time）。
sort_order	String	否	排序方式：asc (升序) 或 desc (降序)。默认为 desc。
start_time	Timestamp	否	查询数据的时间范围起始点（Unix 时间戳）。
end_time	Timestamp	否	查询数据的时间范围结束点（Unix 时间戳）。

返回数据结构

接口成功调用后，将返回 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) 而异，需要根据平台定义的数据模型来解析。

祝您开发顺利！

​审核编辑 黄宇