使用Opendatasoft API导出端点时offset和limit参数报错

问题背景 #

我尝试用Python调用Opendatasoft API访问lbpd-ripa-data-annual数据集，想用limit和offset实现分页，但条目超10000时无法正常工作。选择exports端点是因为文档明确说明：

records端点返回的记录数量受限，而exports端点无此限制。

records端点有limit+offset≤10000的约束，但exports端点文档未提及该限制。实际测试发现：

• 当offset=1（默认limit=-1即获取全量记录），返回错误：

  Streaming interrupted due to the following error: Invalid value for sum of offset + limit API parameter: 83714 was found but <= 10000 is expected. (error_code: InvalidRESTParameterError)

• 当offset=1&limit=10000，返回错误：

  Invalid value for sum of offset + limit API parameter: 10001 was found but <= 10000 is expected.

• 但offset=0时，不管limit设置多大（比如10001）都能正常返回，推测存在未文档化约束：当offset≠0时，offset+limit必须≤10000。

解决方案 #

方法1：用slice参数绕过限制（推荐） #

Opendatasoft的exports端点支持slice参数，格式为slice=<start>:<end>，可以直接指定记录的起始和结束索引，不受offset+limit的10000限制，适合大数据集分页导出。

示例请求：

• 第一页（0-9999条）：https://data.longbeach.gov/api/explore/v2.1/catalog/datasets/lbpd-ripa-data-annual/exports/csv?slice=0:10000
• 第二页（10000-19999条）：https://data.longbeach.gov/api/explore/v2.1/catalog/datasets/lbpd-ripa-data-annual/exports/csv?slice=10000:20000

Python实现代码：

import requests

dataset_id = "lbpd-ripa-data-annual"
base_url = f"https://data.longbeach.gov/api/explore/v2.1/catalog/datasets/{dataset_id}/exports/csv"
page_size = 10000
current_start = 0

while True:
    params = {"slice": f"{current_start}:{current_start + page_size}"}
    response = requests.get(base_url, params=params)
    
    # 空响应表示已无数据可获取
    if not response.text.strip():
        break
    
    # 将当前页数据保存为CSV文件
    with open(f"dataset_page_{current_start//page_size + 1}.csv", "w", encoding="utf-8") as f:
        f.write(response.text)
    
    current_start += page_size
    print(f"已导出第{current_start//page_size}页数据")

方法2：全量导出后本地分页 #

如果数据集总大小在内存允许范围内，可以直接请求全量数据，再在Python中做本地分页处理：

import pandas as pd
import requests

dataset_id = "lbpd-ripa-data-annual"
url = f"https://data.longbeach.gov/api/explore/v2.1/catalog/datasets/{dataset_id}/exports/csv"

# 下载全量数据
response = requests.get(url)
with open("full_dataset.csv", "w", encoding="utf-8") as f:
    f.write(response.text)

# 本地分页处理
df = pd.read_csv("full_dataset.csv")
page_size = 10000
total_pages = (len(df) + page_size - 1) // page_size

for page_num in range(total_pages):
    start_idx = page_num * page_size
    end_idx = start_idx + page_size
    page_df = df.iloc[start_idx:end_idx]
    page_df.to_csv(f"local_page_{page_num + 1}.csv", index=False)
    print(f"已生成本地分页第{page_num + 1}页")

方法3：使用官方Python SDK #

Opendatasoft提供了官方Python库opendatasoft，可以自动处理分页逻辑，无需手动拼接参数：

from opendatasoft import client

# 初始化客户端
ods_client = client.OpendatasoftClient("https://data.longbeach.gov")
# 获取数据集对象
dataset = ods_client.get_dataset("lbpd-ripa-data-annual")

# 迭代获取所有记录，SDK自动处理分页
for record in dataset.records_iter():
    # 按需处理单条记录
    print(record)

说明 #

slice参数是Opendatasoft API的标准参数，专门用于范围查询，不受offset+limit的限制，是处理大数据集分页的最优方案。如果遇到API参数限制，优先尝试该方法。

内容的提问来源于stack exchange，提问作者Matt S