USDA食品数据API分页获取方法

想要获取USDA食品数据API的完整数据？本文为你提供详细的分页获取教程！由于USDA食品数据API默认返回结果数量有限，本文将深入讲解如何利用pageSize和pageNumber参数，通过Python迭代获取所有食品营养数据。教程包含实用的代码示例、全面的错误处理以及最佳实践，助你构建稳定高效的数据采集流程。掌握API分页机制，轻松获取USDA食品数据，为你的数据分析项目打下坚实基础。本文将指导你如何避免API返回结果数量受限的问题，确保获取全面准确的食品数据，提升数据处理效率。

深入理解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.")

代码解析与注意事项

1. 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 异常。

2. 数据处理与导出:

   • 获取到所有 food_items_data 后，代码遍历每个食品项，提取其描述和所有营养成分。
   • 将这些数据组织成字典列表，然后使用 pandas.DataFrame 转换为数据框。
   • df.loc[:,~df.columns.duplicated()] 这一行用于处理在数据转换过程中可能出现的重复列名（例如，如果API响应中同一个营养素名称出现了多次，尽管通常不会）。这只是一个简单的去重方法，在实际应用中可能需要更复杂的逻辑来合并或区分重复数据。
   • 最后，使用 df.to_excel() 方法将数据框导出到Excel文件，index=False 表示不将DataFrame的索引写入Excel。

3. API密钥安全:

   • 在示例代码中，API_KEY 直接写在代码中。在实际生产环境中，绝不应将API密钥硬编码到代码中或直接暴露在公共仓库中。应使用环境变量、配置文件或密钥管理服务来安全地存储和访问API密钥。

4. 请求频率与限流:

   • 虽然USDA API文档中没有明确提及严格的速率限制，但频繁或高速的请求可能会导致IP被暂时封禁。在处理大量数据时，可以考虑在请求之间添加短暂的延时（例如 time.sleep(0.1)），以模拟更自然的用户行为，减少被限流的风险。

5. 超时设置:

   • timeout=10 参数为每个请求设置了10秒的超时时间。这是一个良好的实践，可以防止程序因网络问题长时间挂起。根据网络环境和API响应速度，可以适当调整此值。

总结

通过本教程，我们学习了如何识别和应对API分页问题，特别是针对USDA食品数据API。核心策略是利用API文档中提供的 pageSize 和 pageNumber 参数，通过迭代请求来获取完整数据集。结合 requests.Session 优化性能、完善的错误处理以及将数据导出到Pandas DataFrame和Excel的实践，开发者可以构建出高效、健壮的数据采集解决方案。在任何API集成中，仔细阅读API文档、理解其工作原理并实施适当的错误处理和安全措施始终是成功的关键。

好了，本文到此结束，带大家了解了《USDA食品数据API分页获取方法》，希望本文对你有所帮助！关注golang学习网公众号，给大家分享更多文章知识！