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 the USDA FoodData Central branded foods dataset, which brand owners submit to the USDA. Every product has source: "usda-fdc".

Endpoint	What it does	Scope
`GET /v1/branded-foods`	Search products with filters	`search-branded-foods`
`GET /v1/branded-foods/categories`	List every category with its product count	`search-branded-foods`
`GET /v1/branded-foods/{id}`	Get one product by its ID	`get-branded-foods`

Search products

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

Parameter	Type	Match	Description
`description`	string	Contains, ignoring case	The product name, such as `cheddar`.
`brand`	string	Contains, ignoring case	Matches the brand owner, brand name, or sub-brand.
`ingredient`	string	Contains, ignoring case	Text in the ingredient list, such as `whey protein`.
`category`	string	Exact, ignoring case	A category from `GET /v1/branded-foods/categories`.
`upc`	string	Exact	The barcode printed on the package.
`limit`	integer	—	Rows per page, 1 to 200. Default `50`.
`cursor`	string	—	The `next_cursor` from the previous 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://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 brand didn’t report is null.
serving_size_unit is the unit exactly as the brand submitted 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://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://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:

curl --request GET \
  --url https://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://api.orbbit.co/v1/branded-foods/data_branded_food_01k2x7f3m9q8r4t6v0w2y5z8ab \
  --header 'authorization: Bearer YOUR_API_KEY'

The response is { "data": { ...product } } — 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 brand didn’t report is null.

Identity

Field	Type	Description
`id`	string	Orbbit’s ID for the product. Starts with `data_branded_food_`.
`fdc_id`	integer	The product’s ID in USDA FoodData Central.
`description`	string	The product name as submitted, such as `SHARP CHEDDAR CHEESE`.
`short_description`	string or null	A shorter name, when the brand gave one.
`upc`	string or null	The barcode (GTIN or UPC) printed on the package.

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 on the package, such as `CRACKER BARREL`.
`subbrand_name`	string or null	The product line within the brand.
`category`	string or null	The product’s category. See `GET /v1/branded-foods/categories`.
`gpc_class_code`	integer or null	The GS1 Global Product Classification code for the product type.

Package and serving

Field	Type	Description
`package_weight`	string or null	The package size as printed, such as `7 oz/198 g`.
`serving_size`	number or null	The serving size, in `serving_size_unit`.
`serving_size_unit`	string or null	The unit exactly as submitted, such as `GRM`.
`serving_size_unit_normalized`	string or null	The same unit in a standard form, such as `g` or `ml`.
`household_serving_text`	string or null	The serving in kitchen terms, such as `1 oz` or `2 cookies`.
`preparation_state_code`	string or null	Whether the nutrition facts are for the food as sold or as prepared.

Market

Field	Type	Description
`market_country`	string or null	The country the product is sold in, as submitted.
`market_country_normalized`	string or null	The same country spelled one way — `United States` and `US` both become `US`.
`trade_channels`	array or null	Where the product is sold, such as retail or food service.

Label

Field	Type	Description
`ingredients`	string or null	The full ingredient list, as printed.
`nutrition`	object	The nutrition facts panel, per serving. See Nutrition.
`nutrients`	array or null	Every nutrient the brand reported, including ones not on the panel.
`attributes`	array or null	Extra label claims and attributes the brand submitted.
`caffeine_statement`	string or null	The caffeine statement, when the label has one.
`footnote`	string or null	Any footnote the brand submitted.

Dates and provenance

Field	Type	Description
`published_on`	string or null	When USDA published the record, `YYYY-MM-DD`.
`available_on`	string or null	When the product became available, `YYYY-MM-DD`.
`modified_on`	string or null	When the brand last changed the record, `YYYY-MM-DD`.
`discontinued_on`	string or null	When the product was discontinued, `YYYY-MM-DD`. `null` if still sold.
`data_source`	string or null	How the brand submitted the data to USDA, such as `GDSN` or `LI`.
`source`	string	Always `usda-fdc`.
`fetched_at`	string or null	When Orbbit last copied the record from USDA, as an ISO 8601 timestamp.

Nutrition

nutrition always has these 15 keys. A value is null when the brand didn’t report it.

Key	Nutrient	Key	Nutrient
`calories`	Energy (kcal)	`fiber`	Dietary fiber
`fat`	Total fat	`sugars`	Total sugars
`saturated_fat`	Saturated fat	`added_sugar`	Added sugars
`trans_fat`	Trans fat	`protein`	Protein
`cholesterol`	Cholesterol	`calcium`	Calcium
`sodium`	Sodium	`iron`	Iron
`carbohydrates`	Total carbohydrates	`potassium`	Potassium
		`vitamin_d`	Vitamin D

Parameter	Match	Notes
`description`	Contains, ignoring case	Matches the product name.
`brand`	Contains, ignoring case	Matches `brand_owner`, `brand_name`, or `subbrand_name`.
`ingredient`	Contains, ignoring case	Matches the `ingredients` text.
`category`	Exact, ignoring case	Use a value from `GET /v1/branded-foods/categories`.
`upc`	Exact	Include leading zeros.

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
Errors	`400`, `401`, `403`	`401`, `403`	`401`, `403`, `404`

What to do next

Try it live — Search branded foods, List categories, and Get a branded food.
See how this fits with D2C data — read the CPG overview.

Getting Started

AI 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