BLS API无法返回CUUR0000SA0系列2022年1月前数据的技术咨询

我正在使用美国劳工统计局（BLS）的API获取CUUR0000SA0系列的消费者价格指数（CPI）数据，目标是获取2020年4月至2024年4月的数据，但API响应仅返回2022年1月及之后的数据，无法获取该日期之前的记录。

调用代码 #

import requests
import json
import pandas as pd

# Constants
CPI_URL = "https://api.bls.gov/publicAPI/v2/timeseries/data/"
API_KEY = "<<MY API KEY>>"

# Function to get CPI data from the API
def get_cpi_data(start_year, end_year):
    headers = {"Content-Type": "application/json"}
    data = json.dumps({
        "seriesid": ["CUUR0000SA0"],
        "startyear": str(start_year),
        "endyear": str(end_year),
        "registrationkey": API_KEY
    })
    response = requests.post(CPI_URL, headers=headers, data=data)
    response_json = response.json()
    
    # Print the API response for debugging purposes
    print(json.dumps(response_json, indent=4))
    
    return response_json

# Test the function with a range of years
start_year = 2020
end_year = 2024  

try:
    cpi_data = get_cpi_data(start_year, end_year)
except ValueError as e:
    print(e)

API返回数据（截断版） #

{
"status": "REQUEST_SUCCEEDED",
"responseTime": 155,
"message": [],
"Results": {
    "series": [
        {
            "seriesID": "CUUR0000SA0",
            "data": [
                {
                    "year": "2024",
                    "period": "M04",
                    "periodName": "April",
                    "latest": "true",
                    "value": "313.548",
                    "footnotes": [
                        {}
                    ]
                },
                ...
                {
                    "year": "2022",
                    "period": "M01",
                    "periodName": "January",
                    "value": "281.148",
                    "footnotes": [
                        {}
                    ]
                }
            ]
        }
    ]
}

技术问询 #

1. 为何API请求无法返回2022年1月之前（含2020年4月）的数据？
2. 是否存在特定限制或需要添加额外参数才能获取所需数据？

解答 #

问题1原因 #

主要有两种可能：

• BLS API对免费用户的单次请求存在隐性数据范围限制，尽管2020-2024的年份范围理论上符合要求，但实际返回时被截断，仅返回最近3年的数据。
• CUUR0000SA0系列CPI在2022年进行过基准调整，跨基准调整的历史数据无法通过单次请求全部返回，API默认仅返回基准调整后的最新数据。

问题2解决方法 #

可以通过以下方式获取完整数据：

1. 分批次请求：将年份范围拆分为多个小区间（如2020-2021、2022-2024），分别发起API请求，再合并返回的数据集。
2. 参数验证与调整：确保startyear和endyear为字符串格式，API Key有效；可尝试添加"outputtype": 0（默认值，返回修订后数据）或"outputtype": 1（返回原始未修订数据）参数，确认是否能触发历史数据返回。

修改后的分批次请求代码示例 #

import requests
import json
import pandas as pd

CPI_URL = "https://api.bls.gov/publicAPI/v2/timeseries/data/"
API_KEY = "<<MY API KEY>>"

def get_cpi_data(start_year, end_year):
    headers = {"Content-Type": "application/json"}
    data = json.dumps({
        "seriesid": ["CUUR0000SA0"],
        "startyear": str(start_year),
        "endyear": str(end_year),
        "registrationkey": API_KEY
    })
    response = requests.post(CPI_URL, headers=headers, data=data)
    return response.json()

def get_full_cpi_data(start_year, end_year):
    all_data = []
    # 按每2年拆分请求区间
    current_start = start_year
    while current_start <= end_year:
        current_end = min(current_start + 1, end_year)
        response_json = get_cpi_data(current_start, current_end)
        # 提取数据并添加到总列表
        if response_json["status"] == "REQUEST_SUCCEEDED":
            series_data = response_json["Results"]["series"][0]["data"]
            all_data.extend(series_data)
        current_start = current_end + 1
    # 按年份和月份排序
    all_data.sort(key=lambda x: (x["year"], x["period"]))
    return all_data

# 获取2020-2024年完整数据
try:
    full_cpi_data = get_full_cpi_data(2020, 2024)
    print(json.dumps(full_cpi_data, indent=4))
except ValueError as e:
    print(e)

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