Skip to content
noms

Noms developer guide

Noms is a REST API for nutritional data: foods, brands, nutrients and food groups, cleaned and normalized into one consistent shape. This guide is the short path to building with it. Get a key, make your first request, and take the example queries straight into your app.

This is a guide, not an exhaustive reference. For the complete, always-current list of every endpoint, parameter and field, open the API explorer, where you can authenticate and run live requests in the browser.

QuickstartMake your first request in five minutes.
Nutrition dataHow per-100 values and serving sizes fit together.
AuthenticationGet an API key and send it with every request.
Querying & data modelSearch, filter, sort, paginate, and shape responses.
Common scenariosCopy-paste recipes for real app features.
Rate limits & quotasQuotas, RateLimit headers, and reading your usage.
SupportHow to reach us, response times, and the status page.
Full API referenceEvery endpoint, parameter and field. Interactive, and always current.
Open the explorer

What you can build

  • Barcode lookup. Scan or type an EAN/UPC and resolve the product.
  • Food search. A typo-tolerant search box over the whole catalog.
  • Nutrition labels. Pull a food's full per-100 g nutrient breakdown.
  • Diet and fitness features. Rank and filter foods by nutrient: high-protein, low-sugar, and so on.

How the API is shaped

A few conventions hold across every endpoint. Learn them once and the whole API feels predictable.

  • One base URL. Everything lives under https://api.noms.sh/v1.
  • One auth header. Send your API key as X-API-Key on every request.
  • JSON envelopes. A single resource comes back as { "data": { … } }; a list as { "data": [ … ], "links": { … }, "meta": { … } }.
  • Keyset pagination. Lists are cursor-paginated. Follow links.next to walk the next page; never count offsets.
  • Shape the payload. Pull in related resources with include=, and trim fields with fields[...], so you fetch exactly what you render.
  • RFC 9457 errors. Failures are application/problem+json with a type, title, status, detail, and a doc_url linking to the explanation.

Make your first request →