> ## Documentation Index
> Fetch the complete documentation index at: https://data-docs.orbbit.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Branded Food

> What's inside packaged foods sold in the US: ingredients, nutrition, serving, barcode, and maker.

Use this when you need to know what's in a packaged food on US shelves: its ingredients, nutrition facts, serving size, and who makes it. Typical uses: find every product that contains an ingredient you supply, check a competitor's formulation, or fill in label data from a barcode.

The data is a copy of USDA FoodData Central's current Branded Foods list, refreshed when USDA publishes. USDA builds that list from label data its partners send: brands through the GS1 network, and label data companies such as Label Insight. Each product's `data_source` says which, and how fresh its data can be. Every product has `source: "usda-fdc"`.

| Endpoint | Name | What it does | Scope | Price |
| - | - | - | - | - |
| `GET /v1/branded-foods` | Search Branded Foods | Search products with filters | `search-branded-foods` | \$0.01 |
| `GET /v1/branded-foods/categories` | List Branded Food Categories | List every category with its product count | `search-branded-foods` | Free |
| `GET /v1/branded-foods/{id}` | Get a Branded Food | Get one product by its ID | `get-branded-foods` | \$0.01 |

## Search products

Every filter is optional. When you pass several, a product must match all of them.

| Parameter | Type | Description |
| - | - | - |
| `description` | string | Text to find in the product name, such as `cheddar`. Capital letters do not matter. Leave it out to search every product. |
| `brand` | string | Text to find in the brand, the company that owns it, or the product line, such as `kraft`. Capital letters do not matter. |
| `ingredient` | string | Text to find in the ingredient list, such as `peanuts`. Capital letters do not matter. |
| `category` | string | One category, spelled in full, such as `Cheese`. Capital letters do not matter. `GET /v1/branded-foods/categories` lists every category. |
| `upc` | string | The full barcode number (GTIN or UPC) printed on the package, such as `016000348516`. |
| `limit` | integer | How many products to return per page, from 1 to 200. The default is 50. |
| `cursor` | string | To get the next page, pass the `next_cursor` from the previous reply. Leave it out for the first page. |

### Your first search: look up a barcode

The simplest search finds one product by the barcode on its package.

```bash Request theme={null}
curl --request GET \
  --url 'https://data-api.orbbit.co/v1/branded-foods?upc=021000601366' \
  --header 'authorization: Bearer YOUR_API_KEY'
```

```json Response theme={null}
{
  "data": [
    {
      "id": "data_branded_food_01k2x7f3m9q8r4t6v0w2y5z8ab",
      "fdc_id": 2345678,
      "description": "SHARP CHEDDAR CHEESE",
      "brand_owner": "Kraft Heinz Foods Company",
      "brand_name": "CRACKER BARREL",
      "category": "Cheese",
      "upc": "021000601366",
      "serving_size": 28,
      "serving_size_unit": "GRM",
      "serving_size_unit_normalized": "g",
      "household_serving_text": "1 oz",
      "ingredients": "CHEDDAR CHEESE (PASTEURIZED MILK, CHEESE CULTURE, SALT, ENZYMES, ANNATTO (COLOR)).",
      "nutrition": {
        "calories": 110,
        "fat": 9,
        "saturated_fat": 6,
        "sodium": 180,
        "protein": 7
      },
      "source": "usda-fdc",
      "fetched_at": "2026-08-23T03:29:33.000Z"
    }
  ],
  "next_cursor": null
}
```

Response trimmed for clarity. Values are illustrative. Every product has the same set of fields; see [Product fields](#product-fields) below for all of them.

### Understanding the response

* `data` is this page of matching products. An empty array means nothing matched.
* `next_cursor` is `null` on the last page. Otherwise, pass it as `cursor` to get the next page.

Results come one page at a time. `limit` sets the page size (1 to 200, default 50). Each response has a `next_cursor`: pass it back as `cursor` to get the next page, and stop when it's `null`. Rows come back in ID order, so paging never skips or repeats a row.

* `nutrition` holds the 15 nutrients on a US nutrition facts panel, per serving. A nutrient the data provider didn't supply is `null`, which does not mean zero.
* `serving_size_unit` is the unit exactly as the data provider wrote it, such as `GRM`. `serving_size_unit_normalized` is the same unit in a standard form, such as `g`. Use the normalized one when you compare products.

## Find products that contain an ingredient

This finds snack bars that list whey protein, 20 at a time.

```bash theme={null}
curl --request GET \
  --url 'https://data-api.orbbit.co/v1/branded-foods?ingredient=whey%20protein&category=Snack%2C%20Energy%20%26%20Granola%20Bars&limit=20' \
  --header 'authorization: Bearer YOUR_API_KEY'
```

## Find a brand's products

`brand` matches the company that owns the brand, the brand, and the sub-brand, so either the maker or the label name works.

```bash theme={null}
curl --request GET \
  --url 'https://data-api.orbbit.co/v1/branded-foods?brand=cracker%20barrel&description=cheddar' \
  --header 'authorization: Bearer YOUR_API_KEY'
```

## Find valid categories

`category` must match a category name exactly, apart from case. Get the list first. This call is free:

```bash Request theme={null}
curl --request GET \
  --url https://data-api.orbbit.co/v1/branded-foods/categories \
  --header 'authorization: Bearer YOUR_API_KEY'
```

```json Response theme={null}
{
  "data": [
    { "category": "Candy", "product_count": 41210 },
    { "category": "Cheese", "product_count": 23874 }
  ]
}
```

Response trimmed for clarity. Values are illustrative. Categories come back largest first.

## Get one product

Pass an `id` from a search result. This endpoint needs the `get-branded-foods` scope.

```bash theme={null}
curl --request GET \
  --url https://data-api.orbbit.co/v1/branded-foods/data_branded_food_01k2x7f3m9q8r4t6v0w2y5z8ab \
  --header 'authorization: Bearer YOUR_API_KEY'
```

The response is `{ "data": { ...product } }`, with the same fields a search returns. An unknown ID returns `404`:

```json 404 Unknown product theme={null}
{
  "error": {
    "type": "not_found",
    "message": "Unknown branded food: data_branded_food_01k2x7f3m9q8r4t6v0w2y5z8ab"
  }
}
```

## Product fields

Every product, from search or from `GET /v1/branded-foods/{id}`, has all of these fields. A field the data provider didn't supply is `null`. These descriptions are the same ones the API reference and the Orbbit Data MCP tools give.

### Identity

| Field | Type | Description |
| - | - | - |
| `id` | string | Orbbit's ID for the product. Pass it to `GET /v1/branded-foods/{id}`. |
| `fdc_id` | integer | The record's ID in USDA FoodData Central. When the data provider updates a product, USDA publishes it as a new record with a new ID. |
| `description` | string | The product name as the data provider wrote it, such as `SHARP CHEDDAR CHEESE`. |
| `short_description` | string or null | The brand's abbreviated product name for shelf tags and till receipts, such as `Prog Trad Hrty Chkn Rotini Sp`. Present almost only on `GDSN` products; empty for the rest. |
| `upc` | string or null | The barcode number (GTIN or UPC) that identifies the product, with leading zeros. |

### Brand and category

| Field | Type | Description |
| - | - | - |
| `brand_owner` | string or null | The company that owns the brand, such as `Kraft Heinz Foods Company`. |
| `brand_name` | string or null | The brand printed on the package, such as `CRACKER BARREL`. Store brands appear here too, such as `SAM'S CHOICE`. |
| `subbrand_name` | string or null | The product line within the brand, such as `ULTRA` for Organic Valley. |
| `category` | string or null | The product's category, assigned by the data source (GDSN or Label Insight), not by USDA. `GET /v1/branded-foods/categories` lists every value. |
| `gpc_class_code` | integer or null | The GS1 Global Product Classification code for the product type, at class level, such as `50131700` (milk and milk substitutes). Present only on `GDSN` and `Euromonitor` products. |

### Package and serving

| Field | Type | Description |
| - | - | - |
| `package_weight` | string or null | The net contents printed on the package, such as `7 oz/198 g`. Present mostly on `LI` and `NZGDSN` products. |
| `serving_size` | number or null | The serving size the nutrition facts are based on, in `serving_size_unit`. |
| `serving_size_unit` | string or null | The serving unit as the data provider wrote it: `g` or `GRM` for grams, `ml` or `MLT` for milliliters. A few products show `MG` or `IU`, which are provider errors. |
| `serving_size_unit_normalized` | string or null | The same unit written one way: `g`, `ml`, `mg` or `IU`. Orbbit adds it so products can be compared. |
| `household_serving_text` | string or null | The serving in kitchen terms, as printed, such as `2 Tbsp` or `1 LINK`. |
| `preparation_state_code` | string or null | Which state of the food the nutrition values describe, such as `UNPREPARED` (as sold), `PREPARED` or `READY_TO_EAT`. Present only on some `GDSN` products. |

### Market

| Field | Type | Description |
| - | - | - |
| `market_country` | string or null | The country where the product is sold, as the data provider wrote it: `United States`, `US` or `New Zealand`. |
| `market_country_normalized` | string or null | The same country written one way: `US` or `NZ`. Orbbit adds it so products can be compared. |
| `trade_channels` | array or null | Where the brand says the product is sold: `GROCERY` (food retail), `FOOD_SERVICE` (restaurants, hotels, clubs), `CHILD_NUTRITION_FOOD_PROGRAMS` (approved for school meal programs) or `ONLINE`. `NO_TRADE_CHANNEL` means none was given, which is true of most products. |

### Label

| Field | Type | Description |
| - | - | - |
| `ingredients` | string or null | The ingredient list as it appears on the label. |
| `nutrition` | object | The Nutrition Facts panel, per serving, as the data provider supplied it. A nutrient missing here was not supplied; it does not mean zero. Values are label values, which are rounded, not lab tests. |
| `nutrients` | array or null | Every nutrient USDA holds for the product, per 100 g or 100 ml, calculated by USDA from the per-serving label values. Each one says how it was calculated, such as "Calculated from value per serving size measure". |
| `attributes` | array or null | USDA's update log for the product: what changed in this version, such as `Nutrient Updated`, `Description` or `Food Discontinued`. A nutrient change can be a corrected error, not a new recipe. Empty for most products. |
| `caffeine_statement` | string or null | The caffeine statement printed on the label, such as `80MG CAFFEINE`. Present only on some `LI` products. |
| `footnote` | string or null | A note from USDA about the record, such as a correction made in a past release. Present on very few products. |

### Dates and provenance

| Field | Type | Description |
| - | - | - |
| `published_on` | string or null | The day USDA published this version of the record to FoodData Central, `YYYY-MM-DD`. USDA publishes changes monthly. |
| `available_on` | string or null | The day the product record became available for USDA to add to FoodData Central, `YYYY-MM-DD`. It is not the day the product went on sale. |
| `modified_on` | string or null | The last day the data provider (the brand, or Label Insight) changed this product's data, `YYYY-MM-DD`. For `LI` products this is on or before 2023-11-16, because that source stopped. An old date means no newer data reached USDA, not that Orbbit's copy is out of date. |
| `discontinued_on` | string or null | The day the product was discontinued, as the data provider reported it, `YYYY-MM-DD`. Most products have none, including some no longer sold. |
| `data_source` | string or null | Where USDA got this product's data. `LI` is Label Insight, a label data company that stopped sending USDA updates on November 16, 2023. `GDSN` is the brand's own data sent through the GS1 network, which brands can update at any time. `Euromonitor` and `NZGDSN` (New Zealand brands through GS1) are smaller sources. |
| `source` | string | Always `usda-fdc`: USDA FoodData Central. |
| `fetched_at` | string or null | When Orbbit last copied this record from USDA, as an ISO 8601 timestamp. |

## Nutrition

`nutrition` always has these 15 keys, per serving.

| Key | Description |
| - | - |
| `calories` | Energy per serving, in kcal, as printed on the label. Null when the data provider did not supply it, which does not mean zero. |
| `fat` | Total fat per serving, in grams, as printed on the label. Null when the data provider did not supply it, which does not mean zero. |
| `saturated_fat` | Saturated fat per serving, in grams, as printed on the label. Null when the data provider did not supply it, which does not mean zero. |
| `trans_fat` | Trans fat per serving, in grams, as printed on the label. Null when the data provider did not supply it, which does not mean zero. |
| `cholesterol` | Cholesterol per serving, in milligrams, as printed on the label. Null when the data provider did not supply it, which does not mean zero. |
| `sodium` | Sodium per serving, in milligrams, as printed on the label. Null when the data provider did not supply it, which does not mean zero. |
| `carbohydrates` | Total carbohydrates per serving, in grams, as printed on the label. Null when the data provider did not supply it, which does not mean zero. |
| `fiber` | Dietary fiber per serving, in grams, as printed on the label. Null when the data provider did not supply it, which does not mean zero. |
| `sugars` | Total sugars per serving, in grams, as printed on the label. Null when the data provider did not supply it, which does not mean zero. |
| `added_sugar` | Added sugars per serving, in grams, as printed on the label. Null when the data provider did not supply it, which does not mean zero. |
| `protein` | Protein per serving, in grams, as printed on the label. Null when the data provider did not supply it, which does not mean zero. |
| `calcium` | Calcium per serving, in milligrams, as printed on the label. Null when the data provider did not supply it, which does not mean zero. |
| `iron` | Iron per serving, in milligrams, as printed on the label. Null when the data provider did not supply it, which does not mean zero. |
| `potassium` | Potassium per serving, in milligrams, as printed on the label. Null when the data provider did not supply it, which does not mean zero. |
| `vitamin_d` | Vitamin D per serving, in micrograms, as printed on the label. Null when the data provider did not supply it, which does not mean zero. |

## Search filters

| Parameter | Description |
| - | - |
| `description` | Text to find in the product name, such as `cheddar`. Capital letters do not matter. Leave it out to search every product. |
| `brand` | Text to find in the brand, the company that owns it, or the product line, such as `kraft`. Capital letters do not matter. |
| `ingredient` | Text to find in the ingredient list, such as `peanuts`. Capital letters do not matter. |
| `category` | One category, spelled in full, such as `Cheese`. Capital letters do not matter. `GET /v1/branded-foods/categories` lists every category. |
| `upc` | The full barcode number (GTIN or UPC) printed on the package, such as `016000348516`. |

## Validation rules

| Rule | Behavior |
| - | - |
| All filters optional | No filters returns every product, one page at a time. |
| Filters combine | Several filters mean a product must match all of them. |
| Empty filter | `?brand=` with no text is the same as leaving it out. |
| `limit` | A whole number from 1 to 200. Above 200 returns `400 at most 200 per page`. |
| Order | Results are sorted by `id`, so paging is stable. |

## Summary

| Detail | `GET /v1/branded-foods` | `GET /v1/branded-foods/categories` | `GET /v1/branded-foods/{id}` |
| - | - | - | - |
| Scope | `search-branded-foods` | `search-branded-foods` | `get-branded-foods` |
| Response | `{ data: [product], next_cursor }` | `{ data: [{ category, product_count }] }` | `{ data: product }` |
| Paged | Yes | No | No |
| Price | \$0.01 per call | Free | \$0.01 per call |
| Errors | `400`, `401`, `402`, `403` | `401`, `403` | `401`, `402`, `403`, `404` |

## What to do next

* Try it live: [Search Branded Foods](https://data-docs.orbbit.co/api-reference/branded-food/search-branded-foods.md), [List Branded Food Categories](https://data-docs.orbbit.co/api-reference/branded-food/list-branded-food-categories.md), and [Get a Branded Food](https://data-docs.orbbit.co/api-reference/branded-food/get-a-branded-food.md).
* Copy a working feature: see the [Branded Food Labels cookbook examples](https://github.com/orbbit-tech/orbbit-data-cookbook/tree/main/examples/branded-food-labels).
* See how this fits with commodity prices: read the [CPG overview](https://data-docs.orbbit.co/industry-data/cpg/overview.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.