Filtering and vocabularies

All of these are optional and they combine. GET /recipes, which needs a business plan, 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. So is one whose label was published per 100 g rather than per serving (nutrition.basis.type is 100g), because turning that into a per-serving figure needs a weight the recipe does not carry. 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.

Every recipe feature payload assesses the EU’s 14 regulated allergens plus the distinct US definitions for wheat and tree nuts. Read them from allergens, keyed by identifier.

To leave recipes with an allergen out, pass its identifiers as without, such as without=milk,peanuts, to GET /recipes, GET /search or GET /pantry. They keep only recipes that contain none of them, so a search can return fewer results than limit. GET /popular has no allergen filter; check allergens on each recipe instead.

Each allergen is true when the recipe contains it and false when it does not, counting optional lines and garnishes. It says nothing about manufacturer cross-contact. This data is informational, not medical advice; always verify ingredients and product labels.

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.