USDA Agricultural Research Service (ARS) Food Search API

openapi: 3.2.0
info:
  title: USDA FoodData Central Food Search API
  description: The USDA FoodData Central (FDC) API provides access to an integrated data system with extended nutritional and food component data. Data types include Foundation Foods, SR Legacy, Survey Foods (FNDDS), Branded Foods, and Experimental Foods. Requires a free data.gov API key.
  version: '1.0'
  contact:
    name: USDA National Agricultural Library - FoodData Central
    url: https://fdc.nal.usda.gov/api-guide/
  license:
    name: CC0 1.0 Universal
    url: https://creativecommons.org/publicdomain/zero/1.0/
servers:
- url: https://api.nal.usda.gov/fdc/v1
security:
- ApiKeyQuery: []
tags:
- name: Food Search
  description: Search foods by keywords or other criteria
paths:
  /foods/search:
    get:
      tags:
      - Food Search
      operationId: searchFoodsGet
      summary: Search Foods by Keywords
      description: Returns foods matching the search query. Supports boolean AND/OR operators. Returns up to 50 results per page.
      parameters:
      - name: query
        in: query
        required: true
        description: One or more keywords to search for
        schema:
          type: string
        example: cheddar cheese
      - name: dataType
        in: query
        description: Filter by data type(s)
        schema:
          type: array
          items:
            type: string
            enum:
            - Foundation
            - Branded
            - Survey (FNDDS)
            - SR Legacy
            - Experimental
        style: form
        explode: false
      - name: pageSize
        in: query
        description: Number of results per page (max 200)
        schema:
          type: integer
          default: 50
          maximum: 200
      - name: pageNumber
        in: query
        schema:
          type: integer
          default: 1
      - name: sortBy
        in: query
        schema:
          type: string
          enum:
          - dataType.keyword
          - lowercaseDescription.keyword
          - fdcId
          - publishedDate
      - name: sortOrder
        in: query
        schema:
          type: string
          enum:
          - asc
          - desc
      - name: brandOwner
        in: query
        description: Filter by brand owner (Branded Foods only)
        schema:
          type: string
      - name: api_key
        in: query
        schema:
          type: string
      responses:
        '200':
          description: Food search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResult'
        '400':
          description: Bad request
    post:
      tags:
      - Food Search
      operationId: searchFoodsPost
      summary: Search Foods by Keywords (POST)
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                query:
                  type: string
                  description: Search keywords
                dataType:
                  type: array
                  items:
                    type: string
                pageSize:
                  type: integer
                  default: 50
                pageNumber:
                  type: integer
                  default: 1
                sortBy:
                  type: string
                sortOrder:
                  type: string
                brandOwner:
                  type: string
      responses:
        '200':
          description: Food search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResult'
components:
  schemas:
    SearchResult:
      type: object
      description: Food search response
      properties:
        totalHits:
          type: integer
          description: Total matching foods
        currentPage:
          type: integer
        totalPages:
          type: integer
        foods:
          type: array
          items:
            $ref: '#/components/schemas/SearchResultFood'
    AbridgedFoodNutrient:
      type: object
      properties:
        nutrientId:
          type: integer
        nutrientName:
          type: string
        nutrientNumber:
          type: string
        unitName:
          type: string
        value:
          type: number
    SearchResultFood:
      type: object
      properties:
        fdcId:
          type: integer
        description:
          type: string
        dataType:
          type: string
        publishedDate:
          type: string
          format: date
        brandOwner:
          type:
          - string
          - 'null'
        brandName:
          type:
          - string
          - 'null'
        ingredients:
          type:
          - string
          - 'null'
        foodNutrients:
          type: array
          items:
            $ref: '#/components/schemas/AbridgedFoodNutrient'
        foodCategory:
          type:
          - string
          - 'null'
  securitySchemes:
    ApiKeyQuery:
      type: apiKey
      in: query
      name: api_key
      description: data.gov API key. Register at https://api.data.gov/signup/
    ApiKeyHeader:
      type: apiKey
      in: header
      name: X-Api-Key