foods

List foods

Return a keyset-paginated page of the food catalog — the primary endpoint.

Embed related resources with include= (brand, food_group, nutrients, serving_sizes, images, market_countries); filter on columns, relations (brand_name, market_countries), and per-nutrient values (nutrient[CODE][op]); sort on columns or a nutrient value (sort=-nutrient[PROTEIN]); trim with fields[<resource>]; and search with ?q=.

get/v1/foods

Request

  • Base URL: https://api.noms.sh
  • URL: https://api.noms.sh/v1/foods
  • Auth: API key in header X-API-Key

Query parameters

page_sizeinteger nullable

Number of items to return per page (keyset pagination). Allowed range is 1–20; a value outside it is rejected with a 400.

Example:20
cursorstring nullable

Opaque keyset-pagination cursor. Don't build it by hand; follow links.next from a previous response to fetch the next page.

sortstring nullable

Sort key; prefix with - for descending (-name). Comma-join keys for tie-breakers. Defaults to the resource's natural order.

Example:-name
includestring nullable

Comma-separated related resources to embed in each item: brand, food_group, nutrients, serving_sizes, images, market_countries. Relations load only when requested.

Example:brand,nutrients
qstring nullable

Typo-tolerant text search. Filters to matching rows and, when no sort is given, orders them by relevance. Composes with filters and pagination.

Example:chocolat
fields[foods]string

Sparse fieldset. A comma-separated subset of foods fields to return (e.g. id,name). Omit to return all fields.

fields[brands]string

Sparse fieldset. A comma-separated subset of brands fields to return (e.g. id,name). Omit to return all fields.

fields[food-groups]string

Sparse fieldset. A comma-separated subset of food-groups fields to return (e.g. id,name). Omit to return all fields.

fields[nutrients]string

Sparse fieldset. A comma-separated subset of nutrients fields to return (e.g. id,name). Omit to return all fields.

fields[serving_sizes]string

Sparse fieldset. A comma-separated subset of serving_sizes fields to return (e.g. descriptor,grams). Omit to return all fields.

fields[images]string

Sparse fieldset. A comma-separated subset of images fields to return (e.g. type,url). Omit to return all fields.

fields[market_countries]string

Sparse fieldset. A comma-separated subset of market_countries fields to return (e.g. country_code). Omit to return all fields.

barcodestring

Filter on barcode. Bare barcode=value means eq; the bracket form names the operator — barcode[eq], barcode[in]. barcode[in] takes a comma-separated list. Rows with no value for the field never match.

brand_idstring

Filter on brand_id. Bare brand_id=value means eq; the bracket form names the operator — brand_id[eq], brand_id[in]. brand_id[in] takes a comma-separated list. Rows with no value for the field never match.

brand_namestring

Filter on brand_name. Bare brand_name=value means eq; the bracket form names the operator — brand_name[eq], brand_name[in]. brand_name[in] takes a comma-separated list. Rows with no value for the field never match.

country_of_originstring

Filter on country_of_origin. Bare country_of_origin=value means eq; the bracket form names the operator — country_of_origin[eq], country_of_origin[in]. country_of_origin[in] takes a comma-separated list. Rows with no value for the field never match.

food_group_idstring

Filter on food_group_id. Bare food_group_id=value means eq; the bracket form names the operator — food_group_id[eq], food_group_id[in]. food_group_id[in] takes a comma-separated list. Rows with no value for the field never match.

idstring

Filter on id. Bare id=value means eq; the bracket form names the operator — id[eq], id[in]. id[in] takes a comma-separated list. Rows with no value for the field never match.

is_foundationalstring

Filter on is_foundational. Bare is_foundational=value means eq; the bracket form names the operator — is_foundational[eq]. Rows with no value for the field never match.

market_countriesstring

Filter on market_countries. Bare market_countries=value means eq; the bracket form names the operator — market_countries[eq], market_countries[in]. market_countries[in] takes a comma-separated list. Rows with no value for the field never match.

namestring

Filter on name. Bare name=value means eq; the bracket form names the operator — name[eq], name[in]. name[in] takes a comma-separated list. Rows with no value for the field never match.

nutrient[CODE][op]number

Filter on a nutrient's per-100 value. CODE is a nutrient id from GET /v1/nutrients and op is one of eq, gt, gte, lt, lte. Repeat the parameter to apply several constraints at once. A food with no value recorded for that nutrient never matches.

Headers

If-None-Matchstring

An ETag from a previous response for this URL. If it still matches, the API answers 304 Not Modified with no body; otherwise you get the full 200. Either way the request is metered.

Response

A page of foods. Each data item is the flat food resource; nested objects (brand, food_group, nutrients, serving_sizes, images, market_countries) appear only when requested via include=, and fields[<resource>] may trim the keys present.

Example response

{
  "data": [
    {
      "barcode": "00041570110645",
      "basis_unit": "grams",
      "brand": {
        "id": "XoluRyOx9o3C",
        "name": "Blue Diamond"
      },
      "brand_id": "XoluRyOx9o3C",
      "food_group": {
        "icon_url": "https://images.noms.sh/60f440137489aed9240588a68ffebf455102b257021bfa1cde4d6f6b0b28ac6e",
        "id": "NUTS_AND_SEEDS",
        "name": "Nuts & Seeds"
      },
      "food_group_id": "NUTS_AND_SEEDS",
      "id": "TIgbNPnzCIjX",
      "images": [
        {
          "type": "photo",
          "url": "https://images.noms.sh/60f440137489aed9240588a68ffebf455102b257021bfa1cde4d6f6b0b28ac6e"
        }
      ],
      "ingredients_text": "Almonds, sunflower oil, sea salt.",
      "is_foundational": false,
      "market_countries": [
        {
          "country_code": "US"
        }
      ],
      "name": "Roasted salted almonds",
      "nutrients": [
        {
          "id": "PROTEIN",
          "name": "Protein",
          "unit": "g",
          "value": "21.428571"
        }
      ],
      "serving_sizes": [
        {
          "grams": "28.0",
          "is_default": true,
          "quantity": "28.0",
          "unit": "g"
        }
      ]
    }
  ],
  "links": {
    "next": "https://api.noms.sh/v1/foods?page_size=2&cursor=eyJ2IjpbeyJ0IjoicmF3IiwidiI6Ik1pbGsifV0sInMiOiIrbmFtZSJ9",
    "self": "https://api.noms.sh/v1/foods?page_size=2"
  },
  "meta": {
    "has_more": true,
    "page_size": 10
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.