对于可能返回大量数据的API端点,AlphaFinance采用分页机制来控制每次请求返回的数据量,提高API性能和用户体验。本文档将详细介绍如何使用分页功能有效地获取大型数据集。
分页参数
在请求中,您可以使用以下参数控制分页行为:
基本分页示例
以下是使用page和limit参数进行分页的基本示例:
分页响应格式
启用分页的API响应包含pagination对象,提供关于当前分页状态和总数据量的信息:
pagination对象包含以下字段:
current_page:当前页码
total_pages:总页数
total_items:总结果数量
items_per_page:每页项目数
has_next_page:是否有下一页
has_prev_page:是否有上一页
使用偏移量进行分页
除了基于页码的分页外,您还可以使用offset参数直接指定起始位置:
page和offset参数不应同时使用。如果同时提供,API将优先使用offset。
游标分页
对于某些需要处理大量数据的API端点,我们还提供了基于游标的分页方式:
使用游标分页时,API响应会包含cursor字段:
cursor:用于获取下一页结果的游标
has_more:是否有更多结果可用
游标值是一个不透明的字符串,其内容和格式可能会更改。请不要尝试解析或构造游标值。
分页最佳实践
-
设置合理的
limit值:
- 对于需要展示给用户的数据,选择适合您UI的
limit值(如10-20)
- 对于需要批量处理的数据,可以使用较大的
limit值(如50-100)
- 避免设置过小的
limit值,这会导致过多的API调用
-
使用正确的分页类型:
- 对于UI分页(用户可以跳转到特定页面),使用基于
page的分页
- 对于”加载更多”按钮或无限滚动,使用基于
offset或游标的分页
-
处理空结果:
- 当请求的页码超出可用范围时,API将返回空数据数组,而不是错误
- 始终检查
pagination.total_items或has_more字段来确定是否有更多数据
-
并行请求注意事项:
- 避免同时发送大量并行分页请求,这可能触发速率限制
- 考虑使用批处理端点(如果可用)而不是多个分页请求
示例代码
以下是在不同编程语言中实现分页请求的示例:
适用于分页的端点
以下是支持分页的主要API端点:
- 股票搜索:
/v1/stock/search
- 股票列表:
/v1/stock/list
- 行业成分:
/v1/industry/constituents
- 指数成分:
/v1/indices/constituents
- 公司公告:
/v1/events/announcements
- 财务报表:
/v1/financials/income-statement(等财务类端点)
相关资源