> ## Documentation Index
> Fetch the complete documentation index at: https://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 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`](#find-valid-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.

<CodeGroup>
  ```bash Request theme={null}
  curl --request GET \
    --url 'https://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
  }
  ```
</CodeGroup>

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

```bash theme={null}
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.

```bash theme={null}
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:

<CodeGroup>
  ```bash Request theme={null}
  curl --request GET \
    --url https://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 }
    ]
  }
  ```
</CodeGroup>

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://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`:

```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 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](#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     |

## Search filters

| 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](/api-reference/branded-food/search-branded-foods), [List categories](/api-reference/branded-food/list-categories), and [Get a branded food](/api-reference/branded-food/get-a-branded-food).
* **See how this fits with D2C data** — read the [CPG overview](/industry-data/cpg/overview).