Filtering and vocabularies

All of these are optional and they combine. GET /recipes takes:

• cuisine, course, diet — one value from the closed list below.
• category, ingredient — one slug from an open set.
• ingredients, excludeIngredients — 1 to 20 comma-separated names or ids. A recipe must carry every name in ingredients and none in excludeIngredients.
• equipment — 1 to 20 comma-separated equipment names. A recipe must list every one of them.
• language — a two-letter code, such as en.
• maxTotalMinutes, maxCookMinutes — 1 to 10080 minutes, inclusive.
• time — a preset: under-15, under-30 or weekend.
• maxCalories, maxSodium, minFiber, minProtein — per-serving amounts: kilocalories, milligrams of sodium, grams of fiber and grams of protein. See below.
• nutrition — one or more presets: high-fiber, high-protein, low-calorie, low-sodium. See below.
• limit, offset — a page of 1 to 100 recipes, 20 by default, and where it starts.

diet only returns recipes known to suit it. A recipe whose flag is unknown is left out rather than guessed at, so a filtered list is safe to show to someone who actually needs it.

The lists below are also served live by GET /vocabularies, which is the version to build against — this page is a snapshot for reading.

Every nutrition filter is per serving and inclusive, and reads the figures the recipe was published with — nothing is recalculated.maxCalories takes kilocalories, maxSodium milligrams, and minFiber and minProtein grams. A recipe that published a nutrient in another unit is converted, not skipped.

A recipe that carries no nutrition is left out, the same way an unknown diet flag is. Filtering by nutrition therefore returns fewer recipes than the same filter without it.

nutrition takes one or more presets instead of numbers. Calories and protein are the everyday reading of the words; sodium and fiber use the US FDA's labelling thresholds, which are the only widely agreed numbers.

• high-fiber — at least 5 g of fiber per serving.
• high-protein — at least 20 g of protein per serving.
• low-calorie — at most 400 kcal per serving.
• low-sodium — at most 140 mg of sodium per serving.

A preset and an explicit amount for the same nutrient both apply, and the tighter of the two wins, so neither can quietly widen the other.

The fourteen allergens EU food labelling must declare. These appear on a recipe's allergens field; there is no allergen filter.

Every ingredient quantity carries one of these, or none at all — a bare number is a count of pieces. Source spellings are mapped onto them, so Swedish “msk” arrives as tbsp.

Two filters are not closed lists.

• category is a normalized slug from an open set — pasta, soup, bread. Read them off the categories field of recipes you already have.
• ingredient is a canonical ingredient id such as chicken-thigh. GET /ingredients lists them, most used first.

Both must be slugs: lower-case letters, digits and single hyphens. Main Course is rejected; main-course is not.