Skip to main content

分页

对于可能返回大量数据的API端点,AlphaFinance采用分页机制来控制每次请求返回的数据量,提高API性能和用户体验。本文档将详细介绍如何使用分页功能有效地获取大型数据集。

分页参数

在请求中,您可以使用以下参数控制分页行为:

基本分页示例

以下是使用pagelimit参数进行分页的基本示例:

分页响应格式

启用分页的API响应包含pagination对象,提供关于当前分页状态和总数据量的信息:
pagination对象包含以下字段:
  • current_page:当前页码
  • total_pages:总页数
  • total_items:总结果数量
  • items_per_page:每页项目数
  • has_next_page:是否有下一页
  • has_prev_page:是否有上一页

使用偏移量进行分页

除了基于页码的分页外,您还可以使用offset参数直接指定起始位置:
pageoffset参数不应同时使用。如果同时提供,API将优先使用offset

游标分页

对于某些需要处理大量数据的API端点,我们还提供了基于游标的分页方式:
使用游标分页时,API响应会包含cursor字段:
  • cursor:用于获取下一页结果的游标
  • has_more:是否有更多结果可用
游标值是一个不透明的字符串,其内容和格式可能会更改。请不要尝试解析或构造游标值。

分页最佳实践

  1. 设置合理的limit
    • 对于需要展示给用户的数据,选择适合您UI的limit值(如10-20)
    • 对于需要批量处理的数据,可以使用较大的limit值(如50-100)
    • 避免设置过小的limit值,这会导致过多的API调用
  2. 使用正确的分页类型
    • 对于UI分页(用户可以跳转到特定页面),使用基于page的分页
    • 对于”加载更多”按钮或无限滚动,使用基于offset或游标的分页
  3. 处理空结果
    • 当请求的页码超出可用范围时,API将返回空数据数组,而不是错误
    • 始终检查pagination.total_itemshas_more字段来确定是否有更多数据
  4. 并行请求注意事项
    • 避免同时发送大量并行分页请求,这可能触发速率限制
    • 考虑使用批处理端点(如果可用)而不是多个分页请求

示例代码

以下是在不同编程语言中实现分页请求的示例:

适用于分页的端点

以下是支持分页的主要API端点:
  • 股票搜索:/v1/stock/search
  • 股票列表:/v1/stock/list
  • 行业成分:/v1/industry/constituents
  • 指数成分:/v1/indices/constituents
  • 公司公告:/v1/events/announcements
  • 财务报表:/v1/financials/income-statement(等财务类端点)

相关资源