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 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-creamtoo. - 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 takes the pantry as
ingredients. - GET /recipes filters on
ingredient,ingredientsandexcludeIngredients. It needs a business plan. - GET /substitutions takes the ingredients to replace.
- GET /ingredients/{id} and GET /ingredients/{id}/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} returns everything the API knows about one ingredient:
namesandaliases, the canonical name and every spelling seen, by language.parent, the food it is a kind or a part of, such aschickenforchicken-thigh.allergensanddietary, the same questions a recipe answers, for this one ingredient.substitutions, what to use instead and how much.densityandpourable, 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 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 assumes you have them. They come back in
assumedIngredientsand are never counted as missing. Sendstaples=falseto count them. - GET /ingredients/{id}/pairings leaves them out, because they go with everything. Send
staples=trueto include them.