Endpoints

Batch Lookup

Look up multiple foods in a single request. Eliminates the N+1 problem for apps resolving a grocery list, a meal's ingredients, or a day's food log.

Request body

{
    "ids": ["3f2a1b9c-2e1a-4b8b-9e0a-6b7c8d9e0f1a", "a9b8c7d6-1234-4b8b-9e0a-6b7c8d9e0f1a", "c3d4e5f6-1234-4b8b-9e0a-6b7c8d9e0f1a"]
  }

Maximum 50 IDs per request. Results are returned in the same order as the input. Any ID that doesn't match a food is returned as null in that slot.

Example response

Each non-null item has the same shape as GET /v1/foods/{id} (see Food Detail for every field). Only a few representative fields are shown below. The rest, including nutrients and portions, are omitted for brevity.

{
    "data": [
      {
        "id": "3f2a1b9c-2e1a-4b8b-9e0a-6b7c8d9e0f1a",
        "name": "Chicken breast, grilled",
        "category": { "slug": "poultry", "name": "Poultry" },
        "energyKcal": 165,
        "proteinG": 31.0,
        "fatG": 3.6,
        "carbsG": 0
      },
      {
        "id": "a9b8c7d6-1234-4b8b-9e0a-6b7c8d9e0f1a",
        "name": "Almonds",
        "category": { "slug": "nuts_seeds", "name": "Nuts & Seeds" },
        "energyKcal": 579,
        "proteinG": 21.2,
        "fatG": 49.9,
        "carbsG": 21.6
      },
      null
    ]
  }

Errors

An unknown ID within an otherwise valid batch is not an error, it resolves to null in that slot. See Error handling for the common error codes every endpoint can return.