---
title: "Ingredients — Tiny Plates recipe API"
description: "How the API names ingredients: canonical ids, names in the recipe’s own language, turning what people type into ids, and where each id can be used."
url: "https://www.tinyplates.dev/docs/ingredients"
---

# Ingredients

Every ingredient has a canonical id, such as chicken-thigh or double-cream. The id is the same whatever language a recipe is written in, so it is what you filter, group and look things up by.

## Ids and names

An id is a lower-case English slug for one food: singular, with one spelling. “Tomatoes”, “tomat” and “Tomate” are all `tomato`. Every spelling the API has seen is kept with the ingredient, keyed by language:

```
{
  "aliases": {
    "en": [
      "butter",
      "unsalted butter",
      "salted butter"
    ],
    "de": [
      "Butter"
    ],
    "sv": [
      "smör",
      "osaltat smör"
    ]
  },
  "id": "butter",
  "name": "butter"
}
```

Each line in a recipe’s `ingredients` carries two sets of names. The canonical ones are for your code: `ingredientId` and `name`, in English. The reader’s ones are in the recipe’s language: `localName` and `localPreparation` when they differ, and `display`, the whole line ready to show. So you can group a Swedish and an English recipe by `ingredientId` without translating either of them.

`ingredientId` is absent on a line the API could not match to an ingredient, and on a recipe that has only just been collected. `name` is always there.

## From a name to an id

People type “heavy cream” or “fresh cilantro”, not ids. [GET /ingredients/resolve](https://www.tinyplates.dev/docs/api/resolve-ingredients) turns up to 20 names into ids in one request:

```
curl 'https://api.tinyplates.dev/ingredients/resolve?names=fresh+cilantro,heavy+cream,unicorn+dust' \
  -H 'Authorization: Bearer rd_your_api_key'
```

```
{
  "ingredients": [
    {
      "id": "cilantro",
      "name": "cilantro",
      "query": "fresh-cilantro"
    },
    {
      "id": "double-cream",
      "name": "double cream",
      "query": "heavy-cream"
    }
  ],
  "unknown": [
    "unicorn-dust"
  ]
}
```

* A name matches an id, or any spelling in any language, so “vispgrädde” finds `double-cream` too.
* A name that matches nothing falls back to the food it is a kind or a part of. “Boneless chicken thighs” finds `chicken-thigh`.
* Words that name another food are never dropped, so “sweet potato” does not become `potato`.
* A name with no match comes back in `unknown`, never as a guess.

## Where ids go

* [GET /pantry](https://www.tinyplates.dev/docs/api/pantry-recipes) takes the pantry as `ingredients`.
* [GET /recipes](https://www.tinyplates.dev/docs/api/list-recipes) filters on `ingredient`, `ingredients` and `excludeIngredients`. It needs a business plan.
* [GET /substitutions](https://www.tinyplates.dev/docs/api/substitutions) takes the ingredients to replace.
* [GET /ingredients/{id}](https://www.tinyplates.dev/docs/api/get-ingredient) and [GET /ingredients/{id}/pairings](https://www.tinyplates.dev/docs/api/ingredient-pairings) take one id in the path.

The pantry and the recipe filters also accept a canonical name, such as `double cream`, with a space and a hyphen treated alike. They do not look up other spellings. When the names come from a person, resolve them first and send the ids.

## What an ingredient holds

[GET /ingredients/{id}](https://www.tinyplates.dev/docs/api/get-ingredient) returns everything the API knows about one ingredient:

* `names` and `aliases`, the canonical name and every spelling seen, by language.
* `parent`, the food it is a kind or a part of, such as `chicken` for `chicken-thigh`.
* `allergens` and `dietary`, the same questions a recipe answers, for this one ingredient.
* `substitutions`, what to use instead and how much.
* `density` and `pourable`, which unit conversion uses to turn a volume into a weight.
* `recipeCount`, how many recipes use it.

A field the API has not worked out yet is left out rather than guessed. [Pairings](https://www.tinyplates.dev/docs/api/ingredient-pairings) are a separate request, because they are counted from the recipes.

## Staples

Salt, pepper, water, oil, sugar and flour are in nearly every recipe and nearly every kitchen. An ingredient’s `staple` field says whether it is one of them, and two endpoints treat them differently by default:

* [GET /pantry](https://www.tinyplates.dev/docs/api/pantry-recipes) assumes you have them. They come back in `assumedIngredients` and are never counted as missing. Send `staples=false` to count them.
* [GET /ingredients/{id}/pairings](https://www.tinyplates.dev/docs/api/ingredient-pairings) leaves them out, because they go with everything. Send `staples=true` to include them.
