---
title: "Filtering and vocabularies — Tiny Plates recipe API"
description: "Filter recipes by cuisine, course, category, diet, ingredient, language and total time, and the closed vocabularies each filter accepts."
url: "https://www.tinyplates.dev/docs/filtering"
---

# Filtering and vocabularies

Recipes come from sites that each classify things their own way, so the pipeline maps everything onto closed lists. A filter takes a value from one of these lists — anything else is rejected with a message that says so.

## The filters

All of these are optional and they combine. [GET /recipes](https://www.tinyplates.dev/docs/api/list-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.

```
curl 'https://api.tinyplates.dev/recipes?cuisine=italian&diet=vegetarian&maxTotalMinutes=30' \
  -H 'Authorization: Bearer rd_your_api_key'
```

`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](https://www.tinyplates.dev/docs/api/vocabularies), which is the version to build against — this page is a snapshot for reading.

## Nutrition

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.

```
curl 'https://api.tinyplates.dev/recipes?nutrition=high-protein,low-calorie&maxSodium=500' \
  -H 'Authorization: Bearer rd_your_api_key'
```

## Cuisines

* `african`
* `american`
* `argentinian`
* `asian`
* `australian`
* `austrian`
* `belgian`
* `brazilian`
* `british`
* `cajun`
* `caribbean`
* `chinese`
* `cuban`
* `danish`
* `dutch`
* `eastern-european`
* `egyptian`
* `ethiopian`
* `filipino`
* `finnish`
* `french`
* `german`
* `greek`
* `hungarian`
* `indian`
* `indonesian`
* `iranian`
* `irish`
* `israeli`
* `italian`
* `jamaican`
* `japanese`
* `korean`
* `latin-american`
* `lebanese`
* `malaysian`
* `mediterranean`
* `mexican`
* `middle-eastern`
* `moroccan`
* `norwegian`
* `pakistani`
* `peruvian`
* `polish`
* `portuguese`
* `russian`
* `scandinavian`
* `southern-us`
* `spanish`
* `swedish`
* `swiss`
* `tex-mex`
* `thai`
* `turkish`
* `vietnamese`

## Courses

* `appetizer`
* `breakfast`
* `brunch`
* `dessert`
* `dinner`
* `drink`
* `lunch`
* `main-course`
* `side-dish`
* `snack`

## Diets

* `dairy-free`
* `gluten-free`
* `pescatarian`
* `vegan`
* `vegetarian`

## Allergens

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](https://www.tinyplates.dev/docs/api/list-recipes), [GET /search](https://www.tinyplates.dev/docs/api/search-recipes) or [GET /pantry](https://www.tinyplates.dev/docs/api/pantry-recipes). They keep only recipes that contain none of them, so a search can return fewer results than `limit`. [GET /popular](https://www.tinyplates.dev/docs/api/popular-recipes) 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.

* `celery`(eu)
* `crustaceans`(eu/us)
* `eggs`(eu/us)
* `fish`(eu/us)
* `gluten-cereals`(eu)
* `lupin`(eu)
* `milk`(eu/us)
* `molluscs`(eu)
* `mustard`(eu)
* `nuts-eu`(eu)
* `peanuts`(eu/us)
* `sesame`(eu/us)
* `soy`(eu/us)
* `sulphites`(eu)
* `tree-nuts-us`(us)
* `wheat`(us)

## Units

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`.

* `g`
* `kg`
* `lb`
* `oz`
* `cl`
* `cup`
* `dl`
* `fl-oz`
* `gallon`
* `l`
* `ml`
* `pint`
* `quart`
* `tbsp`
* `tsp`
* `bag`
* `bottle`
* `box`
* `bunch`
* `can`
* `clove`
* `cube`
* `dash`
* `drop`
* `ear`
* `handful`
* `head`
* `jar`
* `knob`
* `leaf`
* `package`
* `packet`
* `piece`
* `pinch`
* `portion`
* `pot`
* `scoop`
* `sheet`
* `shot`
* `slice`
* `sprig`
* `stalk`
* `stick`
* `tub`
* `cm`
* `inch`

## Categories and ingredients

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](https://www.tinyplates.dev/docs/api/list-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.