> ## 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. # Search Branded Foods > Search for packaged food products by name, brand, category, barcode, or ingredient.. Requires the `search-branded-foods` scope. ## OpenAPI ````yaml /api-reference/openapi.json get /v1/branded-foods openapi: 3.1.0 info: title: Orbbit Data API version: '1.0' description: Commodity prices and packaged-food labels over one read-only REST API. servers: - url: https://data-api.orbbit.co description: Production security: - bearer: [] tags: - name: Commodities - name: Branded Food paths: /v1/branded-foods: get: tags: - Branded Food summary: Search Branded Foods description: >- Search for packaged food products by name, brand, category, barcode, or ingredient.. Requires the `search-branded-foods` scope. operationId: search_branded_foods parameters: - name: description required: false in: query description: >- Text to find in the product name, such as `cheddar`. Capital letters do not matter. Leave it out to search every product. schema: type: string - name: brand required: false in: query description: >- Text to find in the brand, the company that owns it, or the product line, such as `kraft`. Capital letters do not matter. schema: type: string - name: category required: false in: query description: >- One category, spelled in full, such as `Cheese`. Capital letters do not matter. `GET /v1/branded-foods/categories` lists every category. schema: type: string - name: upc required: false in: query description: >- The full barcode number (GTIN or UPC) printed on the package, such as `016000348516`. schema: type: string - name: ingredient required: false in: query description: >- Text to find in the ingredient list, such as `peanuts`. Capital letters do not matter. schema: type: string - name: limit required: false in: query description: >- How many products to return per page, from 1 to 200. The default is 50. schema: type: integer - name: cursor required: false in: query description: >- To get the next page, pass the `next_cursor` from the previous reply. Leave it out for the first page. schema: type: string responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/SearchBrandedFoodsResponseDto' example: data: - id: data_branded_food_01k2x7f3m9q8r4t6v0w2y5z8ab fdc_id: 2345678 description: SHARP CHEDDAR CHEESE short_description: null brand_owner: Kraft Heinz Foods Company brand_name: CRACKER BARREL subbrand_name: null category: Cheese gpc_class_code: 10000013 upc: '021000601366' package_weight: 7 oz/198 g serving_size: 28 serving_size_unit: GRM serving_size_unit_normalized: g household_serving_text: 1 oz preparation_state_code: null market_country: United States market_country_normalized: US trade_channels: - NO_TRADE_CHANNEL ingredients: >- CHEDDAR CHEESE (PASTEURIZED MILK, CHEESE CULTURE, SALT, ENZYMES, ANNATTO (COLOR)). nutrition: calories: 110 fat: 9 saturated_fat: 6 trans_fat: 0 cholesterol: 30 sodium: 180 carbohydrates: 0 fiber: 0 sugars: 0 added_sugar: 0 protein: 7 calcium: 200 iron: 0 potassium: 20 vitamin_d: 0 nutrients: [] attributes: [] caffeine_statement: null footnote: null data_source: GDSN published_on: '2024-10-31' available_on: '2024-10-31' modified_on: '2024-09-12' discontinued_on: null source: usda-fdc fetched_at: '2026-08-23T03:29:33.000Z' next_cursor: data_branded_food_01k2x7f3m9q8r4t6v0w2y5z8ab '400': description: >- The limit is not between 1 and 200, or the cursor is not one this API returned. content: application/json: schema: $ref: '#/components/schemas/PublicApiErrorDto' example: error: type: invalid_request message: 'limit: at most 200 per page' '401': description: The API key is missing, mistyped, unknown or revoked. content: application/json: schema: $ref: '#/components/schemas/PublicApiErrorDto' example: error: type: unauthorized message: 'Missing or malformed Authorization: Bearer header' '402': description: >- The balance, or this key's monthly spend limit, cannot cover this call. content: application/json: schema: $ref: '#/components/schemas/PublicApiErrorDto' example: error: type: insufficient_balance message: Insufficient balance '403': description: This API key is not allowed to call this endpoint. content: application/json: schema: $ref: '#/components/schemas/PublicApiErrorDto' example: error: type: forbidden message: This key is not scoped to search-branded-foods security: - bearer: [] components: schemas: SearchBrandedFoodsResponseDto: type: object properties: data: type: array items: type: object properties: id: type: string description: >- Orbbit's ID for the product. Pass it to `GET /v1/branded-foods/{id}`. fdc_id: type: number description: >- 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: type: string description: >- The product name as the data provider wrote it, such as `SHARP CHEDDAR CHEESE`. short_description: anyOf: - type: string - type: 'null' description: >- 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. brand_owner: anyOf: - type: string - type: 'null' description: >- The company that owns the brand, such as `Kraft Heinz Foods Company`. brand_name: anyOf: - type: string - type: 'null' description: >- The brand printed on the package, such as `CRACKER BARREL`. Store brands appear here too, such as `SAM'S CHOICE`. subbrand_name: anyOf: - type: string - type: 'null' description: >- The product line within the brand, such as `ULTRA` for Organic Valley. category: anyOf: - type: string - type: 'null' description: >- 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: anyOf: - type: number - type: 'null' description: >- 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. upc: anyOf: - type: string - type: 'null' description: >- The barcode number (GTIN or UPC) that identifies the product, with leading zeros. package_weight: anyOf: - type: string - type: 'null' description: >- The net contents printed on the package, such as `7 oz/198 g`. Present mostly on `LI` and `NZGDSN` products. serving_size: anyOf: - type: number - type: 'null' description: >- The serving size the nutrition facts are based on, in `serving_size_unit`. serving_size_unit: anyOf: - type: string - type: 'null' description: >- 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: anyOf: - type: string - type: 'null' description: >- The same unit written one way: `g`, `ml`, `mg` or `IU`. Orbbit adds it so products can be compared. household_serving_text: anyOf: - type: string - type: 'null' description: >- The serving in kitchen terms, as printed, such as `2 Tbsp` or `1 LINK`. preparation_state_code: anyOf: - type: string - type: 'null' description: >- 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_country: anyOf: - type: string - type: 'null' description: >- The country where the product is sold, as the data provider wrote it: `United States`, `US` or `New Zealand`. market_country_normalized: anyOf: - type: string - type: 'null' description: >- The same country written one way: `US` or `NZ`. Orbbit adds it so products can be compared. trade_channels: anyOf: - type: array items: {} - type: 'null' description: >- 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. ingredients: anyOf: - type: string - type: 'null' description: The ingredient list as it appears on the label. nutrition: type: object properties: calories: anyOf: - type: number - type: 'null' description: >- 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: anyOf: - type: number - type: 'null' description: >- 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: anyOf: - type: number - type: 'null' description: >- 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: anyOf: - type: number - type: 'null' description: >- 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: anyOf: - type: number - type: 'null' description: >- 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: anyOf: - type: number - type: 'null' description: >- 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: anyOf: - type: number - type: 'null' description: >- 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: anyOf: - type: number - type: 'null' description: >- 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: anyOf: - type: number - type: 'null' description: >- 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: anyOf: - type: number - type: 'null' description: >- 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: anyOf: - type: number - type: 'null' description: >- 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: anyOf: - type: number - type: 'null' description: >- 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: anyOf: - type: number - type: 'null' description: >- 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: anyOf: - type: number - type: 'null' description: >- 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: anyOf: - type: number - type: 'null' description: >- 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. required: - calories - fat - saturated_fat - trans_fat - cholesterol - sodium - carbohydrates - fiber - sugars - added_sugar - protein - calcium - iron - potassium - vitamin_d description: >- 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: anyOf: - type: array items: {} - type: 'null' description: >- 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: anyOf: - type: array items: {} - type: 'null' description: >- 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: anyOf: - type: string - type: 'null' description: >- The caffeine statement printed on the label, such as `80MG CAFFEINE`. Present only on some `LI` products. footnote: anyOf: - type: string - type: 'null' description: >- A note from USDA about the record, such as a correction made in a past release. Present on very few products. data_source: anyOf: - type: string - type: 'null' description: >- 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. published_on: anyOf: - type: string - type: 'null' description: >- The day USDA published this version of the record to FoodData Central, `YYYY-MM-DD`. USDA publishes changes monthly. available_on: anyOf: - type: string - type: 'null' description: >- 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: anyOf: - type: string - type: 'null' description: >- 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: anyOf: - type: string - type: 'null' description: >- The day the product was discontinued, as the data provider reported it, `YYYY-MM-DD`. Most products have none, including some no longer sold. source: type: string description: 'Always `usda-fdc`: USDA FoodData Central.' fetched_at: anyOf: - type: string - type: 'null' description: >- When Orbbit last copied this record from USDA, as an ISO 8601 timestamp. required: - id - fdc_id - description - short_description - brand_owner - brand_name - subbrand_name - category - gpc_class_code - upc - package_weight - serving_size - serving_size_unit - serving_size_unit_normalized - household_serving_text - preparation_state_code - market_country - market_country_normalized - trade_channels - ingredients - nutrition - nutrients - attributes - caffeine_statement - footnote - data_source - published_on - available_on - modified_on - discontinued_on - source - fetched_at description: The products on this page. x-nestjs_zod-uses-3-point-1-syntax: true next_cursor: anyOf: - type: string - type: 'null' description: Pass as `cursor` to get the next page. `null` on the last page. x-nestjs_zod-uses-3-point-1-syntax: true x-nestjs_zod-empty-type: true required: - data - next_cursor PublicApiErrorDto: type: object properties: error: type: object properties: type: type: string message: type: string required: - type - message x-nestjs_zod-self-required: true required: - error securitySchemes: bearer: type: http scheme: bearer description: Your API key, which starts with `orbbit_data_`. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.