# NutrientsDB

> A curated global food-composition dataset — ~2.9M food entries across 86 normalized nutrient
> fields, deduplicated across 180+ countries — sold under a one-time license as a downloadable
> dataset for local use. A free, keyless, read-only Sample API exposes a public 1,000-food slice
> with the identical 86-field nutrient schema, so you can inspect the shape of the data before
> licensing it. There are no subscriptions and no per-call fees on the licensed product.

Generated by API Evangelist from the provider's published OpenAPI, docs, and dataset mirrors.
NutrientsDB does not publish its own llms.txt — /llms.txt on nutrientsdb.com returns the
single-page-app HTML shell, not a document.

## Scope

- The Sample API serves ONLY the public 1,000-food sample. A 404 from it means "not in the sample",
  not "not in NutrientsDB".
- The full ~2.9M-food dataset is a downloadable file, not a hosted API. There is no endpoint that
  queries it.
- All nutrient values are per 100 g of food. A null value means the source did not report that
  nutrient — it does not mean zero.

## APIs

- [NutrientsDB Sample API](https://www.nutrientsdb.com/api/docs): Free, keyless, read-only REST API
  over the public 1,000-food sample. One operation, `findFoods`, at
  `GET https://www.nutrientsdb.com/api/foods`. No authentication, HTTPS only, CORS enabled for all
  origins, 20-result maximum.

## Specs

- [OpenAPI 3.1.0 (provider-published)](https://www.nutrientsdb.com/api/openapi): The authoritative
  machine-readable contract for the Sample API.
- [Food JSON Schema (API Evangelist derived)](json-schema/nutrientsdb-food.json): The Food record
  with the nutrients map expanded into all 86 named, unit-typed fields.
- [Nutrient vocabulary](vocabulary/nutrientsdb-nutrient-schema.yml): All 86 nutrient field names
  with units, groupings, and descriptions, verified 86/86 against a live API payload.

## Usage

Search by food name (`q` is 2-100 characters, `limit` defaults to 10 and caps at 20):

    curl "https://www.nutrientsdb.com/api/foods?q=banana&limit=3"

Retrieve one food by its stable `public_id`:

    curl "https://www.nutrientsdb.com/api/foods?id=2923506"

`q` and `id` are mutually exclusive selectors. Search responses carry `count`, `total_matches`, and
`limit`; there is no cursor, offset, or page parameter, so results beyond `limit` are not
retrievable through this API.

## Errors

Errors are `application/json` (NOT RFC 9457 problem+json) shaped `{sample: {...}, error: "..."}`.
The `sample` block appears on success and error alike, so branch on the HTTP status:

- `400` — neither `q` nor `id` supplied, or `q` shorter than 2 characters.
- `404` — the `public_id` is not in the 1,000-food sample.

See [the error catalog](errors/nutrientsdb-problem-types.yml).

## Docs

- [Sample API documentation](https://www.nutrientsdb.com/api/docs)
- [Nutrient field reference](https://www.nutrientsdb.com/docs)
- [Features](https://www.nutrientsdb.com/features)
- [Pricing](https://www.nutrientsdb.com/pricing)
- [Blog](https://www.nutrientsdb.com/blog)
- [Contact](https://www.nutrientsdb.com/contact)
- [Terms](https://www.nutrientsdb.com/terms) / [Privacy](https://www.nutrientsdb.com/privacy)

## Data mirrors

- [GitHub sample + schema reference](https://github.com/colinearstudio/nutrientsdb-sample):
  `sample.json` (1,000 foods) plus the full 86-field reference table.
- [Hugging Face dataset](https://huggingface.co/datasets/colinearstudio/nutrientsdb): the same
  sample, loadable via `datasets`, `pandas`, or `polars`.

## Not available

NutrientsDB publishes no MCP server, no A2A agent card, no client SDKs, no webhooks or event
stream, no status page, no changelog, and no /.well-known documents. Every `/.well-known/*` path
and `/llms.txt` on the site returns HTTP 200 with the SPA HTML shell — treat those 200s as absent,
not present.