深入理解API分页机制与USDA食品数据API实践
在使用外部api获取数据时，开发者经常会遇到返回结果数量受限的情况。这通常是由于api采用了分页（pagination）机制，旨在优化性能、减少带宽消耗并防止单次请求返回过大数据量。美国农业部（usda）的食品数据中心（food data central, fdc）api也不例外，其搜索接口在默认情况下可能只返回少量结果（例如50条）。本教程将详细讲解如何识别并处理这种分页机制，从而获取完整的usda食品营养数据。
识别API分页
当通过API进行数据查询，但发现返回的数据量远低于预期时，首先应查阅该API的官方文档。对于USDA FDC API，其文档（例如SwaggerHub上的Food Data Central API）会明确指出搜索结果是分页的。在API响应中，通常会包含指示当前页码（currentPage）和总页数（totalPages）的字段。此外，文档还会说明控制分页行为的参数，例如：
- pageSize: 每页返回结果的最大数量。USDA API允许将此参数设置为最大200。
- pageNumber: 指定要获取的页码。
理解这些参数是获取全部数据的关键。
分页获取完整数据的实现
为了获取所有符合条件的食品数据，我们需要编写一个循环，迭代请求每一页的数据，并将它们累积起来。以下是使用Python requests 库实现此逻辑的示例代码：
import requests
import json
import pandas as pd
def get_all_usda_foods(query_term, api_key, page_size=200):
"""
从USDA食品数据API分页获取所有符合查询条件的食品数据。
参数:
query_term (str): 查询的食品名称或关键词。
api_key (str): USDA API的授权密钥。
page_size (int): 每页返回的结果数量，最大为200。
返回:
list: 包含所有食品数据字典的列表，如果发生错误则返回None。
"""
all_foods = []
# 构造初始URL，设置每页大小
base_url = f"https://api.nal.usda.gov/fdc/v1/foods/search?api_key={api_key}&query={query_term}&pageSize={page_size}"
with requests.Session() as session: # 使用requests.Session保持连接，提高效率
try:
# 第一次请求，获取总页数
print(f"Fetching initial page for query: '{query_term}'")
response = session.get(base_url, timeout=10)
response.raise_for_status() # 检查HTTP请求是否成功
api_response = response.json()
# 检查API响应结构，确保'foods'和'totalPages'存在
if "foods" not in api_response or "totalPages" not in api_response:
print("Error: 'foods' or 'totalPages' not found in initial API response.")
return None
all_foods.extend(api_response["foods"])
total_pages = api_response["totalPages"]
print(f"Total pages to fetch: {total_pages}")
# 从第二页开始循环获取所有数据
for page_num in range(2, total_pages + 1):
print(f"Fetching page {page_num}/{total_pages}...")
page_url = f"{base_url}&pageNumber={page_num}"
page_response = session.get(page_url, timeout=10)
page_response.raise_for_status()
page_api_response = page_response.json()
if "foods" in page_api_response:
all_foods.extend(page_api_response["foods"])
else:
print(f"Warning: 'foods' not found in response for page {page_num}.")
break # 如果某一页没有'foods'，可能表示数据结束或API行为异常
except requests.exceptions.HTTPError as http_err:
print(f"HTTP error occurred: {http_err} - Status Code: {http_err.response.status_code}")
return None
except requests.exceptions.ConnectionError as conn_err:
print(f"Connection error occurred: {conn_err}")
return None
except requests.exceptions.Timeout as timeout_err:
print(f"Request timed out: {timeout_err}")
return None
except requests.exceptions.RequestException as req_err:
print(f"An unexpected request error occurred: {req_err}")
return None
except json.JSONDecodeError as json_err:
print(f"Failed to decode JSON response: {json_err}")
print(f"Response content: {response.text[:500]}...") # 打印部分响应内容辅助调试
return None
except Exception as e:
print(f"An unexpected error occurred: {e}")
return None
return all_foods
# 使用示例
if __name__ == "__main__":
API_KEY = "YOUR_USDA_API_KEY" # 替换为你的USDA API密钥
search_term = "raw fruit" # 示例查询词
print(f"Starting data retrieval for '{search_term}'...")
food_items_data = get_all_usda_foods(search_term, API_KEY)
if food_items_data:
print(f"\nSuccessfully retrieved {len(food_items_data)} food items.")
# 将数据转换为Pandas DataFrame并导出到Excel
processed_data = []
for item in food_items_data:
row = {"Description": item.get("description", "N/A")}
for nutrient in item.get("foodNutrients", []):
nutrient_name = nutrient.get("nutrientName")
nutrient_value = nutrient.get("value")
if nutrient_name and nutrient_value is not None:
row[nutrient_name] = nutrient_value
processed_data.append(row)
df = pd.DataFrame(processed_data)
# 清理列名，处理重复营养素（如果存在）
# 这里只是一个简单的处理，实际应用中可能需要更复杂的逻辑
df = df.loc[:,~df.columns.duplicated()]
output_filename = f'{search_term.replace(" ", "_")}_nutritional_facts.xlsx'
df.to_excel(output_filename, index=False)
print(f"Data exported to {output_filename}")
else:
print("Failed to retrieve food data.")
代码解析与注意事项
-
get_all_usda_foods 函数:
- 参数: 接收查询关键词 (query_term)、API密钥 (api_key) 和可选的 page_size。
- requests.Session(): 使用 requests.Session 可以复用底层的TCP连接，对于多次请求同一个域名，这能显著提高性能。
- 初始请求: 首先发送一个请求来获取第一页的数据，并从中提取 totalPages。这是确定需要循环多少次的关键。
- 循环获取: 从第二页开始，循环直到 totalPages。在每次循环中，构造带有 pageNumber 参数的URL，发送请求，并将返回的 foods 数据添加到 all_foods 列表中。
- 错误处理: 集成了 try-except 块来捕获可能发生的网络错误（如 HTTPError, ConnectionError, Timeout）和JSON解析错误（JSONDecodeError），提高了代码的健壮性。当发生错误时，函数会打印错误信息并返回 None。
- response.raise_for_status(): 这是一个非常有用的方法，如果HTTP请求返回了错误状态码（例如4xx或5xx），它会抛出 HTTPError 异常。
-
数据处理与导出:
- 获取到所有 food_items_data 后，代码遍历每个食品项，提取其描述和所有营养成分。
- 将这些数据组织成字典列表，然后使用 pandas.DataFrame 转换为数据框。
- df.loc[:,~df.columns.duplicated()] 这一行用于处理在数据转换过程中可能出现的重复列名（例如，如果API响应中同一个营养素名称出现了多次，尽管通常不会）。这只是一个简单的去重方法，在实际应用中可能需要更复杂的逻辑来合并或区分重复数据。
- 最后，使用 df.to_excel() 方法将数据框导出到Excel文件，index=False 表示不将DataFrame的索引写入Excel。
-
API密钥安全:
- 在示例代码中，API_KEY 直接写在代码中。在实际生产环境中，绝不应将API密钥硬编码到代码中或直接暴露在公共仓库中。应使用环境变量、配置文件或密钥管理服务来安全地存储和访问API密钥。
-
请求频率与限流:
- 虽然USDA API文档中没有明确提及严格的速率限制，但频繁或高速的请求可能会导致IP被暂时封禁。在处理大量数据时，可以考虑在请求之间添加短暂的延时（例如 time.sleep(0.1)），以模拟更自然的用户行为，减少被限流的风险。
-
超时设置:
- timeout=10 参数为每个请求设置了10秒的超时时间。这是一个良好的实践，可以防止程序因网络问题长时间挂起。根据网络环境和API响应速度，可以适当调整此值。
总结
通过本教程，我们学习了如何识别和应对API分页问题，特别是针对USDA食品数据API。核心策略是利用API文档中提供的 pageSize 和 pageNumber 参数，通过迭代请求来获取完整数据集。结合 requests.Session 优化性能、完善的错误处理以及将数据导出到Pandas DataFrame和Excel的实践，开发者可以构建出高效、健壮的数据采集解决方案。在任何API集成中，仔细阅读API文档、理解其工作原理并实施适当的错误处理和安全措施始终是成功的关键。
