Skip to content
noms

Quickstart

Your first request in five minutes. You'll need an API key; see Authentication to get one. Then export it and call the foods endpoint.

1. Set your key

Keep your key out of source control. Export it as an environment variable your snippets can read:

export NOMS_KEY=noms_sk_live_xxxxxxxxxxxxxxxxxxxxxxxx

2. Make your first request

Search foods with ?q=. The response is a data array plus links and meta for pagination:

GET
curl -G https://api.noms.sh/v1/foods \
  --data-urlencode "q=almonds" \
  --data-urlencode "page_size=1" \
  -H "Authorization: Bearer $NOMS_KEY"
Response
200 OK
{
"data": [
{
"id": "TIgbNPnzCIjX",← stable food id, the /v1/foods/{id} handle
"barcode": "00041570110645",
"name": "Roasted salted almonds",
"description": null,
"scientific_name": null,
"country_of_origin": null,
"ingredients_text": "Almonds, sunflower oil, sea salt.",
"is_foundational": false,
"basis_unit": "grams",← what this food's nutrient values are per 100 of
"brand_id": "XoluRyOx9o3C",
"food_group_id": "NUTS_AND_SEEDS"
}
],
"links": {
"self": "/v1/foods?q=almonds&page_size=1",
"next": "/v1/foods?q=almonds&page_size=1&cursor=b3V0..."← follow this URL for the next page
},
"meta": {
"has_more": true,← true when more results exist
"page_size": 1
}
}

3. Fetch one food with its nutrients

Grab a single food by id and pull in its nutrient breakdown with include=nutrients. Values are per 100 of the food's basis_unit; see Nutrition data for the conversion to a serving:

GET
curl -G https://api.noms.sh/v1/foods/TIgbNPnzCIjX \
  --data-urlencode "include=nutrients,brand" \
  -H "Authorization: Bearer $NOMS_KEY"
Response
200 OK
{
"data": {
"id": "TIgbNPnzCIjX",
"barcode": "00041570110645",
"name": "Roasted salted almonds",
"description": null,
"scientific_name": null,
"country_of_origin": null,
"ingredients_text": "Almonds, sunflower oil, sea salt.",
"is_foundational": false,
"basis_unit": "grams",← values below are per 100 grams, see Nutrition data
"brand_id": "XoluRyOx9o3C",
"food_group_id": "NUTS_AND_SEEDS",
"brand": {← grafted in by include=brand
"id": "XoluRyOx9o3C",
"name": "Blue Diamond"
},
"nutrients": [← per-100 measurements (include=nutrients)
{
"id": "ADDED_SUGARS",
"name": "Sugars, added",
"value": "0.0",
"unit": "g"
},
{
"id": "ALPHA_TOCOPHEROL",
"name": "Vitamin E (alpha-tocopherol)",
"value": "25.1625",
"unit": "mg"
},
{
"id": "BIOTIN",
"name": "Biotin",
"value": "43.214286",
"unit": "mcg"
},
{
"id": "CALCIUM",
"name": "Calcium, Ca",
"value": "285.714286",
"unit": "mg"
},
]
}
}

Next steps