> For the complete documentation index, see [llms.txt](https://docs.january.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.january.ai/rest-api/data-essentials.md).

# Data Essentials

One vocabulary runs through the whole API. Learn these five shapes and every endpoint reads the same way.

### Nutrients

Nutrition is always a map of `snake_case` keys (`calories`, `protein`, `carbohydrates`, `iron`, ...) to a `value` and `unit` pair. Units are canonical — `g`, `mg`, `kcal`, `IU` — and each amount carries its own `unit`, so read it from the `value` rather than assuming one. Keys the database has no `value` for are omitted; a key is never `null`.

### Foods and ids

A food's numeric `id` is interchangeable everywhere: an `id` from search, barcode lookup, autocomplete, a scan detection, or a food log can be passed to food detail, alternatives, logging, or glucose prediction.

### Servings

Search and scans return a food's primary serving. The food-detail endpoint returns the complete serving list, each with an `id`, a human `unit` ("cup, sliced"), a weight in grams, and a scaling factor relative to the primary serving. To log or predict, send the serving `id` plus a `quantity` — nutrition scales exactly.

### Detections

Photo scans and text scans return the same detection object, and the corrections endpoint accepts those detections back verbatim — the round trip type-checks in generated clients. Detections always include at least one serving.

### Measurements and dates

Measurement inputs are `value`-and-`unit` pairs with one metric and one imperial choice (`height` `in` or `cm`, `weight` `lb` or `kg`) — never a bare number with an implied `unit`. Date-range queries are inclusive on both ends; `start` equal to `end` is a valid single-day query. A missing `value` is an absent key, never `null`.