Branded Food

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.

curl --request GET \
  --url 'https://data-api.orbbit.co/v1/branded-foods?upc=021000601366' \
  --header 'authorization: Bearer YOUR_API_KEY'

{
  "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 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.

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.

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:

curl --request GET \
  --url https://data-api.orbbit.co/v1/branded-foods/categories \
  --header 'authorization: Bearer YOUR_API_KEY'

{
  "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.

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:

404 Unknown product

{
  "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.

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, List Branded Food Categories, and Get a Branded Food.
Copy a working feature: see the Branded Food Labels cookbook examples.
See how this fits with commodity prices: read the CPG overview.

Getting Started

For Agents

Market Data

Industry Data

Search products

Your first search: look up a barcode

Understanding the response

Find products that contain an ingredient

Find a brand’s products

Find valid categories

Get one product

Product fields

Identity

Brand and category

Package and serving

Market

Label

Dates and provenance

Nutrition

Search filters

Validation rules

Summary

What to do next

​Search products

​Your first search: look up a barcode

​Understanding the response

​Find products that contain an ingredient

​Find a brand’s products

​Find valid categories

​Get one product

​Product fields

​Identity

​Brand and category

​Package and serving

​Market

​Label

​Dates and provenance

​Nutrition

​Search filters

​Validation rules

​Summary

​What to do next

Search products

Your first search: look up a barcode

Understanding the response

Find products that contain an ingredient

Find a brand’s products

Find valid categories

Get one product

Product fields

Identity

Brand and category

Package and serving

Market

Label

Dates and provenance

Nutrition

Search filters

Validation rules

Summary

What to do next