Skip to content
noms

Common scenarios

Real features, built from the four levers in Querying. Each one is a request you can lift straight into your app.

Barcode → food lookup

The canonical "scan a product" flow: resolve a barcode to a food with an exact filter. Empty data means no match in the catalog.

Send the code as scanned. Barcodes are stored as 14-digit GTINs, and the filter pads your value to that form before matching, so the 12-digit UPC a scanner gives you (041570110645) resolves the same food as 00041570110645:

GET
curl -G https://api.noms.sh/v1/foods \
  --data-urlencode "barcode=041570110645" \
  --data-urlencode "include=brand" \
  -H "Authorization: Bearer $NOMS_KEY"
Response
200 OK
{
"data": [
{
"id": "TIgbNPnzCIjX",
"barcode": "00041570110645",← the canonical GTIN-14 the 12-digit code resolved to
"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",
"brand_id": "XoluRyOx9o3C",
"food_group_id": "NUTS_AND_SEEDS",
"brand": {
"id": "XoluRyOx9o3C",
"name": "Blue Diamond"
}
}
],
"links": {
"self": "/v1/foods?barcode=041570110645",
"next": null
},
"meta": {
"has_more": false,
"page_size": 10
}
}

Power an autocomplete with ?q=. Trim the payload to just what the dropdown shows with fields[foods], and keep the page small for snappy results. A sparse fieldset returns exactly the fields you name, so ask for id if you want it back:

GET
curl -G https://api.noms.sh/v1/foods \
  --data-urlencode "q=chedar chese" \
  --data-urlencode "fields[foods]=id,name,brand_id" \
  --data-urlencode "page_size=5" \
  -H "Authorization: Bearer $NOMS_KEY"
Response
200 OK
{
"data": [
{
"id": "EdRXJHInAjqg",
"name": "Sharp cheddar cheese",← matched past two typos
"brand_id": "ELETQYRrJGh5"
},
{
"id": "3FleO3dlJk6Q",
"name": "Mingles cheddar sour cream",
"brand_id": "3fMsXSaGpkq5"
},
{
"id": "TRUdGUy9AlJ4",
"name": "Smokey cheddar",
"brand_id": "bXLwForHev9r"
},
{
"id": "2GPtKLexfv2m",
"name": "Rippled sour cream & cheddar potato chips",
"brand_id": "DjvsLWiPgDSc"
}
],
"links": {
"self": "/v1/foods?q=chedar+chese&page_size=5",
"next": "/v1/foods?...&cursor=b3V0..."
},
"meta": {
"has_more": true,
"page_size": 5
}
}

Full nutrition breakdown

Render a nutrition label: fetch one food with its nutrients and its serving sizes, then convert each value to the serving. Nutrition data explains the model in full; the short version is value × serving[basis_unit] / 100.

GET
curl -G https://api.noms.sh/v1/foods/TIgbNPnzCIjX \
  --data-urlencode "include=nutrients,serving_sizes" \
  -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 are per 100 grams → divide by serving.grams
"brand_id": "XoluRyOx9o3C",
"food_group_id": "NUTS_AND_SEEDS",
"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"
},
{
"id": "CARBOHYDRATE",
"name": "Carbohydrate, by difference",
"value": "17.857143",
"unit": "g"
},
],
"serving_sizes": [
{
"unit": "g",
"descriptor": null,
"quantity": "28.0",
"grams": "28.0",← value × grams/100 → amount per serving
"milliliters": null,
"is_default": true
},
{
"unit": "each",
"descriptor": "nuts",
"quantity": "28.0",
"grams": "28.0",
"milliliters": null,
"is_default": false
}
]
}
}

Rank & filter by nutrient

Build a diet or fitness feature, such as "highest-protein meats", by sorting on a nutrient value and filtering by group. This one trims the payload with fields[foods], so the rows come back with just the keys the list needs:

GET
curl -G https://api.noms.sh/v1/foods \
  --data-urlencode "food_group_id=MEAT" \
  --data-urlencode "sort=-nutrient[PROTEIN]" \
  --data-urlencode "fields[foods]=id,name,basis_unit" \
  --data-urlencode "page_size=3" \
  -H "Authorization: Bearer $NOMS_KEY"
Response
200 OK
{
"data": [
{
"id": "HcUGQ2h7BU18",
"name": "Filet mignon poivre",← highest protein per 100 g in the group
"basis_unit": "grams"
},
{
"id": "SD4O7gsEv8Fl",
"name": "Artisan sausage, spinach pesto",
"basis_unit": "grams"
},
{
"id": "9Mpi5wXD9I3p",
"name": "Chicken breast pieces",
"basis_unit": "grams"
}
],
"links": {
"self": "/v1/foods?food_group_id=MEAT&sort=-nutrient[PROTEIN]",
"next": "/v1/foods?...&cursor=b3V0..."
},
"meta": {
"has_more": true,
"page_size": 3
}
}

Two things to know when you sort on a nutrient. Sorting by it does not put it in the payload, so add include=nutrients if you want the values. And when you do, name nutrients in fields[foods] as well, or the sparse fieldset trims the grafted relation away with everything else you did not ask for.

Keep going

These are starting points. Combine q, filters, sort, include and fields freely. The API explorer lists every field and operator you can reach.

Next steps