Developer API

Query Food Info's reference nutrition data programmatically. A small, versioned, read-only REST API. Free to start: create an account, generate a key and you get 100 requests a day. Requests authenticate with an API key in the X-Api-Key header.

Overview

Versioned under /api/v1, JSON only, server-to-server (no browser CORS). Reuses the same reference data the site runs on. Create a key in "Your API keys" below; a free account is enough to get one.

Base URL: https://api.food-info.org/api/v1
Format: JSON
Auth: X-Api-Keyheader
Plan: Free tier, or Practitioner for higher limits
OpenAPI: openapi.json

The full OpenAPI 3 description is published at https://api.food-info.org/api/v1/openapi.json, so you can import it into Postman or Insomnia, or generate a typed client, rather than writing one by hand.

Authentication

Send your secret key in the X-Api-Key header on every request. Keys are tied to your account; keep them server-side and never expose them in a browser or mobile app. A missing, invalid or revoked key returns 401.

curl -H "X-Api-Key: YOUR_KEY" \
  "https://api.food-info.org/api/v1/nutrients"

Rate limits

Two tiers. Every read endpoint below works on both; the paid plan buys throughput rather than access. Limits are counted per account, not per key, so generating extra keys does not raise your quota.

Plan	Per minute	Per day	Recipe endpoints
Free	10	100	No (403)
Practitioner	60	10,000	Yes

Every response carries X-RateLimit-Limit-Minute, X-RateLimit-Limit-Day and X-RateLimit-Tier, so you can read your current allowance in-band rather than discovering it on a 429. Exceeding a limit returns 429 with a Retry-After header in seconds, so you can back off precisely.

Endpoints

A leading colon marks a path parameter (e.g. :id). Where shown: limit is 1-100 (default 25); home_nation is an ISO country code (e.g. GB) that prefers that country's reference foods.

GET`/nutrients`

The nutrient catalogue, id, name, unit, category, so you can discover the nutrientId values the reverse-search endpoints take.

GET`/foods/search`

Search foods by name (case-insensitive substring). Params: q (required, ≤200 chars), home_nation, limit. Returns id, description, ndbNumber.

curl -H "X-Api-Key: YOUR_KEY" \
  "https://api.food-info.org/api/v1/foods/search?q=oats&limit=5"

GET`/foods/:id`

A single food by FoodData Central id: id, description, ndbNumber, dataType, publicationDate. 404 if unknown.

GET`/foods/:id/panel`

Full nutrient panel: grouped per-100 g + per-serving amounts and % reference-intake. Params: portionId (optional), source ("UK RI" / "FDA 2016"; default UK RI). 404 if unknown.

GET`/nutrients/:nutrientId/top-foods`

Reverse search: reference foods richest in a nutrient per 100 g, highest first. Params: home_nation, limit.

curl -H "X-Api-Key: YOUR_KEY" \
  "https://api.food-info.org/api/v1/nutrients/1089/top-foods?limit=3"

Response (food ids/amounts illustrative):

{
  "Nutrient": { "Id": 1089, "Name": "Iron, Fe", "Unit": "MG" },
  "Results": [
    { "FoodId": 170554, "Description": "Spices, thyme, dried", "Amount": 123.6 },
    { "FoodId": 169966, "Description": "Seeds, sesame flour",  "Amount": 14.6 }
  ]
}

GET`/nutrients/:nutrientId/bottom-foods`

Inverse of top-foods: reference foods with the least of a nutrient per 100 g. Same params and response shape.

Recipe endpoints (Practitioner)

The two endpoints below need a Practitioner key. A free key reaches them but receives 403 with the required and current tier named in the body. Both are POST and take JSON.

POST`/recipes/parse`

Parses raw ingredient lines into structured quantity, unit and food name. Deterministic text handling only, with no database lookup and no food matching, so it is the cheap call to use when you only need structure. Body: { "lines": ["2 tbsp olive oil", "200g plain flour"] }.

curl -H "X-Api-Key: YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"lines":["2 tbsp olive oil","200g plain flour"]}' \
  "https://api.food-info.org/api/v1/recipes/parse"

POST`/recipes/analyze`

Full analysis: resolves each line to a food, then returns per-serving and per-100 g nutrition with source attribution and review flags for lines it was unsure about. Body takes lines (required), region (ISO country code, biases matching to that country's reference foods) and servings.

Returns ingredients, perServing, per100g, totalGrams, servings, sources, reviewFlags and nutrientGroups. Each nutrient row carries nutrientId, name, unit, perServing, per100g, percentDailyValue and referenceAmount. Check reviewFlags before displaying a result as authoritative.

curl -H "X-Api-Key: YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"lines":["2 eggs","100ml milk"],"region":"GB","servings":2}' \
  "https://api.food-info.org/api/v1/recipes/analyze"

Errors

Status	Meaning
`400`	Invalid input, e.g. blank `q` or a non-positive `nutrientId`. The body is a JSON object with an `error` message.
`401 / 403`	Missing, invalid or revoked key (`401`), or a Practitioner-only endpoint called with a free key (`403`). The `403` body names the tier required and the tier you hold.
`404`	No food or nutrient with that id.
`429`	Rate limit exceeded, see `Retry-After`.

Your API keys

Create a free account

Overview

Authentication

Rate limits

Endpoints

GET/nutrients

GET/foods/search

GET/foods/:id

GET/foods/:id/panel

GET/nutrients/:nutrientId/top-foods

GET/nutrients/:nutrientId/bottom-foods