调用 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)
以下是一个使用 Pythonrequests库调用该接口的简单示例：
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) 而异，需要根据平台定义的数据模型来解析。
祝您开发顺利！