对于可能返回大量数据的API端点，AlphaFinance采用分页机制来控制每次请求返回的数据量，提高API性能和用户体验。本文档将详细介绍如何使用分页功能有效地获取大型数据集。
分页参数
在请求中，您可以使用以下参数控制分页行为：
| 参数名 | 类型 | 默认值 | 最大值 | 描述 |
|---|
limit | 整数 | 20 | 100 | 每页返回的结果数量 |
page | 整数 | 1 | - | 要检索的页码，从1开始 |
offset | 整数 | 0 | - | 结果集的起始位置（与page互斥） |
基本分页示例
以下是使用page和limit参数进行分页的基本示例：
# 获取第一页数据，每页20条
curl -X GET "https://api.alphafin.x-pai.com/v1/stock/search?keyword=银行&limit=20&page=1" \
-H "X-API-KEY: your_api_key_here"
# 获取第二页数据，每页20条
curl -X GET "https://api.alphafin.x-pai.com/v1/stock/search?keyword=银行&limit=20&page=2" \
-H "X-API-KEY: your_api_key_here"
分页响应格式
启用分页的API响应包含pagination对象，提供关于当前分页状态和总数据量的信息：
{
"code": 200,
"message": "success",
"data": [
// 返回的数据项...
],
"pagination": {
"current_page": 2,
"total_pages": 5,
"total_items": 98,
"items_per_page": 20,
"has_next_page": true,
"has_prev_page": true
}
}
pagination对象包含以下字段：
current_page：当前页码total_pages：总页数total_items：总结果数量items_per_page：每页项目数has_next_page：是否有下一页has_prev_page：是否有上一页
使用偏移量进行分页
除了基于页码的分页外，您还可以使用offset参数直接指定起始位置：
# 获取从第0个结果开始的20条数据
curl -X GET "https://api.alphafin.x-pai.com/v1/stock/search?keyword=银行&limit=20&offset=0" \
-H "X-API-KEY: your_api_key_here"
# 获取从第20个结果开始的20条数据
curl -X GET "https://api.alphafin.x-pai.com/v1/stock/search?keyword=银行&limit=20&offset=20" \
-H "X-API-KEY: your_api_key_here"
page和offset参数不应同时使用。如果同时提供，API将优先使用offset。
游标分页
对于某些需要处理大量数据的API端点，我们还提供了基于游标的分页方式：
# 获取第一页数据
curl -X GET "https://api.alphafin.x-pai.com/v1/market/trades?symbol=600519&limit=100" \
-H "X-API-KEY: your_api_key_here"
# 使用返回的游标获取下一页
curl -X GET "https://api.alphafin.x-pai.com/v1/market/trades?symbol=600519&limit=100&cursor=eyJpZCI6MTAwMH0=" \
-H "X-API-KEY: your_api_key_here"
使用游标分页时，API响应会包含cursor字段：
{
"code": 200,
"message": "success",
"data": [
// 返回的数据项...
],
"cursor": "eyJpZCI6MjAwMH0=",
"has_more": true
}
cursor：用于获取下一页结果的游标has_more：是否有更多结果可用
游标值是一个不透明的字符串，其内容和格式可能会更改。请不要尝试解析或构造游标值。
分页最佳实践
-
设置合理的limit值：
- 对于需要展示给用户的数据，选择适合您UI的
limit值（如10-20）
- 对于需要批量处理的数据，可以使用较大的
limit值（如50-100）
- 避免设置过小的
limit值，这会导致过多的API调用
-
使用正确的分页类型：
- 对于UI分页（用户可以跳转到特定页面），使用基于
page的分页
- 对于”加载更多”按钮或无限滚动，使用基于
offset或游标的分页
-
处理空结果：
- 当请求的页码超出可用范围时，API将返回空数据数组，而不是错误
- 始终检查
pagination.total_items或has_more字段来确定是否有更多数据
-
并行请求注意事项：
- 避免同时发送大量并行分页请求，这可能触发速率限制
- 考虑使用批处理端点（如果可用）而不是多个分页请求
示例代码
以下是在不同编程语言中实现分页请求的示例：
import requests
def fetch_all_pages(api_key, endpoint, params):
"""获取所有页面的数据"""
all_data = []
page = 1
has_more = True
while has_more:
# 复制基本参数并添加分页参数
page_params = params.copy()
page_params['page'] = page
page_params['limit'] = 100
# 发送请求
headers = {"X-API-KEY": api_key}
response = requests.get(endpoint, params=page_params, headers=headers)
response_data = response.json()
# 添加当前页数据
all_data.extend(response_data['data'])
# 检查是否有更多页
pagination = response_data.get('pagination', {})
current_page = pagination.get('current_page', 0)
total_pages = pagination.get('total_pages', 0)
has_more = current_page < total_pages
page += 1
return all_data
# 示例用法
api_key = "your_api_key_here"
endpoint = "https://api.alphafin.x-pai.com/v1/stock/search"
params = {"keyword": "银行"}
all_banks = fetch_all_pages(api_key, endpoint, params)
print(f"找到 {len(all_banks)} 家银行相关股票")
适用于分页的端点
以下是支持分页的主要API端点：
- 股票搜索：
/v1/stock/search
- 股票列表：
/v1/stock/list
- 行业成分：
/v1/industry/constituents
- 指数成分：
/v1/indices/constituents
- 公司公告：
/v1/events/announcements
- 财务报表：
/v1/financials/income-statement（等财务类端点）
相关资源
