# Use With AI Tools
Source: https://docs.orbbit.co/ai-agents
Give Claude, Cursor, or VS Code these docs so your AI assistant writes working Orbbit API calls.
You don't have to read these docs yourself. Point your AI coding assistant at them and ask it to build what you need — it will look up the right endpoints, parameters, and fields as it goes.
There are three ways to give it the docs, from most to least capable.
## Connect the docs to your assistant
The docs have their own connector, which lets an AI assistant search and read every page on demand. It uses MCP (Model Context Protocol), the standard way AI tools plug into outside sources.
Connector address: `https://docs.orbbit.co/mcp`
```bash theme={null}
claude mcp add --transport http orbbit-docs https://docs.orbbit.co/mcp
```
Add this to `.cursor/mcp.json` in your project:
```json theme={null}
{
"mcpServers": {
"orbbit-docs": { "url": "https://docs.orbbit.co/mcp" }
}
}
```
Add this to `.vscode/mcp.json` in your project:
```json theme={null}
{
"servers": {
"orbbit-docs": { "type": "http", "url": "https://docs.orbbit.co/mcp" }
}
}
```
You can also open the menu at the top of any page and choose your tool to connect it in one click.
## Give it the whole site as text
If your tool doesn't support connectors, give it the site index instead. It's a plain-text list of every page, written for AI tools to read.
* Index of every page: `https://docs.orbbit.co/llms.txt`
* Every page in one file: `https://docs.orbbit.co/llms-full.txt`
## Copy one page
To hand over a single page, open the menu at the top of that page and choose **Copy page**. It copies the page as plain text, ready to paste into any chat.
## Starter prompt
Paste this into your assistant after connecting the docs. Replace the last line with what you want to build.
```text theme={null}
You are helping me call Orbbit's Data API.
- Read the Orbbit docs (connected as "orbbit-docs", or at https://docs.orbbit.co/llms.txt) before writing any code.
- The base address is https://api.orbbit.co and every path starts with /v1.
- Send my key as "Authorization: Bearer $ORBBIT_API_KEY". Never put the key in code.
- Each endpoint needs its own scope on the key; if a call returns 403, tell me which scope to add.
- Only use endpoints, parameters, and fields that appear in the docs.
Task: pull the last 90 days of daily butter prices and save them as a CSV.
```
Your assistant still needs your API key to make real calls. Create one under **API Keys** in the Orbbit console — see [Authentication](/authentication).
# Get a Branded Food
Source: https://docs.orbbit.co/api-reference/branded-food/get-a-branded-food
/api-reference/openapi.json get /v1/branded-foods/{id}
One packaged food — every field USDA publishes for it.
Requires the `get-branded-foods` scope.
# List Categories
Source: https://docs.orbbit.co/api-reference/branded-food/list-categories
/api-reference/openapi.json get /v1/branded-foods/categories
Every category a search can filter on, with how many products carry it, largest first.
Requires the `search-branded-foods` scope.
# Search Branded Foods
Source: https://docs.orbbit.co/api-reference/branded-food/search-branded-foods
/api-reference/openapi.json get /v1/branded-foods
Search packaged foods by name, brand, category, barcode, or an ingredient they contain; every filter is optional and they combine as AND.
Requires the `search-branded-foods` scope.
# Get Commodity Prices
Source: https://docs.orbbit.co/api-reference/commodities/get-commodity-prices
/api-reference/openapi.json get /v1/commodities/prices
Dated prices for one or many catalog series, in the order asked.
Requires the `get-commodity-prices` scope.
# Search Commodity Series
Source: https://docs.orbbit.co/api-reference/commodities/search-commodity-series
/api-reference/openapi.json get /v1/commodities
List the commodity price series Orbbit vouches for, grouped by commodity.
Requires the `search-commodities` scope.
# API Reference
Source: https://docs.orbbit.co/api-reference/introduction
The base URL, authentication, and conventions shared by every Orbbit Data API endpoint.
Every endpoint below is listed with its parameters, example responses, and a **Try it** button that sends a real request from your browser. For what each data set means and why it's useful, see the **Documentation** tab.
## Base URL
All requests go to:
```text theme={null}
https://api.orbbit.co
```
## Authentication
Send your API key in the `Authorization` header on every request:
```bash theme={null}
--header 'authorization: Bearer YOUR_API_KEY'
```
Each endpoint needs its own scope on the key. See [Authentication](/authentication) for how to create a key and choose its scopes.
## Versions
The version is part of the path. Every endpoint starts with `/v1`.
## Requests and responses
* Every endpoint is a `GET` and only reads data.
* Responses are JSON with `snake_case` field names. A single record comes back as `{ "data": { ... } }`, a list as `{ "data": [ ... ] }`.
* Lists that can be long return one page at a time with a `next_cursor`. Pass it back as `cursor` to get the next page; `null` means you have them all.
* Every error has the same shape, `{ "error": { "type", "message" } }`. See [Errors](/errors).
## Endpoints
| Section | Endpoint | Scope |
| ------------------- | ---------------------------------------------------------------------------------- | ----------------------- |
| Commodities | [`GET /v1/commodities`](/api-reference/commodities/search-commodity-series) | `search-commodities` |
| Commodities | [`GET /v1/commodities/prices`](/api-reference/commodities/get-commodity-prices) | `get-commodity-prices` |
| CPG › Branded Food | [`GET /v1/branded-foods`](/api-reference/branded-food/search-branded-foods) | `search-branded-foods` |
| CPG › Branded Food | [`GET /v1/branded-foods/categories`](/api-reference/branded-food/list-categories) | `search-branded-foods` |
| CPG › Branded Food | [`GET /v1/branded-foods/{id}`](/api-reference/branded-food/get-a-branded-food) | `get-branded-foods` |
| CPG › D2C › Shopify | [`GET /v1/stores`](/api-reference/shopify/search-stores) | `search-stores` |
| CPG › D2C › Shopify | [`GET /v1/stores/{id}`](/api-reference/shopify/get-a-store) | `get-store` |
| CPG › D2C › Shopify | [`GET /v1/stores/{id}/products`](/api-reference/shopify/list-store-products) | `get-store-products` |
| CPG › D2C › Shopify | [`GET /v1/stores/{id}/collections`](/api-reference/shopify/list-store-collections) | `get-store-collections` |
| CPG › D2C › Shopify | [`GET /v1/products/{id}`](/api-reference/shopify/get-a-product) | `get-product` |
# Get a Product
Source: https://docs.orbbit.co/api-reference/shopify/get-a-product
/api-reference/openapi.json get /v1/products/{id}
One product in full: description, gallery, and every variant with its price.
Requires the `get-product` scope.
# Get a Store
Source: https://docs.orbbit.co/api-reference/shopify/get-a-store
/api-reference/openapi.json get /v1/stores/{id}
One store in full: profile, Common Crawl rank, and category mix.
Requires the `get-store` scope.
# List Store Collections
Source: https://docs.orbbit.co/api-reference/shopify/list-store-collections
/api-reference/openapi.json get /v1/stores/{id}/collections
One store’s collections — the merchant’s own groupings of products.
Requires the `get-store-collections` scope.
# List Store Products
Source: https://docs.orbbit.co/api-reference/shopify/list-store-products
/api-reference/openapi.json get /v1/stores/{id}/products
One store’s products, each with its category, hero image, and price range.
Requires the `get-store-products` scope.
# Search Stores
Source: https://docs.orbbit.co/api-reference/shopify/search-stores
/api-reference/openapi.json get /v1/stores
Search the crawled Shopify stores — every filter optional, all combined.
Requires the `search-stores` scope.
The crawl covers stores in every industry. Pass `industry=cpg` to keep only consumer packaged goods brands.
# Authentication
Source: https://docs.orbbit.co/authentication
Create an API key, choose what it may call, and send it with every request.
Every request needs an API key in the `Authorization` header:
```bash theme={null}
curl --request GET \
--url https://api.orbbit.co/v1/commodities \
--header 'authorization: Bearer orbbit_data_YOUR_KEY'
```
A key is the text `orbbit_data_` followed by 64 letters and digits. Keep it secret: anyone holding it can call the API as you.
## Create a key
1. Sign in to the Orbbit console and open **API Keys**.
2. Click **New Key**.
3. Under **Name**, give the key a name you'll recognize later, such as `cost-dashboard-prod`.
4. Under **Spend budget (USD)**, set the most this key may spend in a month.
5. Under **Scope**, tick the endpoints the key may call. A key can only call the endpoints you tick.
6. Click **Create**, then copy the key from the **Save your key** window.
The console shows the full key only once. Orbbit stores a one-way fingerprint of it, not the key itself, so nobody — including Orbbit — can show it to you again. If you lose it, revoke it and create a new one.
The key list shows the last four characters of each key so you can tell them apart.
## Choose what a key may call
Each endpoint needs its own permission, called a scope. Give each key only the scopes it needs: a leaked key that can only search stores can do far less harm than one that can call everything.
| Scope | Lets the key call |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `search-commodities` | [`GET /v1/commodities`](/api-reference/commodities/search-commodity-series) |
| `get-commodity-prices` | [`GET /v1/commodities/prices`](/api-reference/commodities/get-commodity-prices) |
| `search-branded-foods` | [`GET /v1/branded-foods`](/api-reference/branded-food/search-branded-foods) and [`GET /v1/branded-foods/categories`](/api-reference/branded-food/list-categories) |
| `get-branded-foods` | [`GET /v1/branded-foods/{id}`](/api-reference/branded-food/get-a-branded-food) |
| `search-stores` | [`GET /v1/stores`](/api-reference/shopify/search-stores) |
| `get-store` | [`GET /v1/stores/{id}`](/api-reference/shopify/get-a-store) |
| `get-store-products` | [`GET /v1/stores/{id}/products`](/api-reference/shopify/list-store-products) |
| `get-store-collections` | [`GET /v1/stores/{id}/collections`](/api-reference/shopify/list-store-collections) |
| `get-product` | [`GET /v1/products/{id}`](/api-reference/shopify/get-a-product) |
The console labels each scope in plain words — `get-commodity-prices` shows as **Get Commodity Prices**. You can change a key's name, budget, and scopes at any time from **API Keys**. The key itself stays the same.
## When a key is refused
| Status | `error.type` | Why | What to do |
| ------ | -------------- | --------------------------------------------------------------------- | ---------------------------------------------------------- |
| `401` | `unauthorized` | The header is missing or malformed, or the key is unknown or revoked. | Check the header reads `Bearer ` followed by the full key. |
| `403` | `forbidden` | The key is valid but does not have this endpoint's scope. | Add the scope to the key in the console. |
```json 403 — missing scope theme={null}
{
"error": {
"type": "forbidden",
"message": "This key is not scoped to get-commodity-prices"
}
}
```
See [Errors](/errors) for every error the API returns.
## Revoke a key
Open **API Keys**, find the key by its name and last four characters, and click **Revoke**. Requests using it are refused with `401` straight away. Revoking cannot be undone.
## Keep keys safe
* Call the API from your server, never from a browser or mobile app, where anyone can read the key.
* Store keys in a secrets manager or environment variable, not in source code.
* Use a separate key for each app and environment, so you can revoke one without breaking the others.
# Errors
Source: https://docs.orbbit.co/errors
Every error the API returns, in one shape, with what caused it and what to do.
Every error, on every endpoint, has the same shape: a status code and a JSON body with an `error` object. For example, asking for a series that doesn't exist:
```bash theme={null}
curl --request GET \
--url 'https://api.orbbit.co/v1/commodities/prices?series=butter-spot' \
--header 'authorization: Bearer YOUR_API_KEY'
```
```json 400 — unknown series theme={null}
{
"error": {
"type": "invalid_request",
"message": "Unknown series: butter-spot"
}
}
```
| Field | Type | Description |
| --------------- | ------ | ---------------------------------------------------------------------------------------------------------------- |
| `error.type` | string | A stable, machine-readable name for the kind of error. Branch on this. |
| `error.message` | string | A human-readable explanation. Log it, show it to a developer — but don't parse it, since the wording can change. |
## Error types
| Status | `error.type` | What happened | What to do |
| ------ | ----------------- | -------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| `400` | `invalid_request` | A parameter is missing, the wrong type, or out of range. | Fix the request. The message names the parameter. |
| `401` | `unauthorized` | The API key is missing, malformed, unknown, or revoked. | Send `Authorization: Bearer ` with a live key. |
| `403` | `forbidden` | The key is valid but lacks this endpoint's scope. | Add the scope in the console. See [Authentication](/authentication#choose-what-a-key-may-call). |
| `404` | `not_found` | No record has the ID in the path. | Check the ID came from a search result. |
| `5xx` | `internal` | Something went wrong on Orbbit's side. The message is always `An unexpected error occurred`. | Retry with exponential backoff. If it persists, contact support. |
## Common 400 errors
| Endpoint | Message | Cause |
| ---------------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------ |
| `GET /v1/commodities/prices` | `Unknown series: ` | A slug in `series` is not in the catalog. Get valid slugs from `GET /v1/commodities`. |
| `GET /v1/commodities/prices` | — | `series` is missing, has more than 100 slugs, a date is not a real `YYYY-MM-DD` day, or `from` is later than `to`. |
| `GET /v1/branded-foods` | `at most 200 per page` | `limit` is above 200. |
| Any endpoint with `limit` | — | `limit` is not a whole number of at least 1. |
## Retrying
Retry only `5xx` errors. Every other error will fail again until you change the request. Every endpoint only reads data, so retrying a request never changes anything.
```python Python theme={null}
import random, time, requests
def get_with_retry(url, headers, params=None, attempts=5):
for attempt in range(attempts):
response = requests.get(url, headers=headers, params=params)
if response.status_code < 500:
return response
time.sleep(min(2 ** attempt, 30) + random.random())
return response
```
# Introduction
Source: https://docs.orbbit.co/index
Orbbit's Data API: market prices that move every industry, and detailed data on the companies and products inside one industry.
Orbbit's Data API answers two kinds of questions about a business: what its inputs cost, and what it makes and sells. It's one read-only REST API — every endpoint takes an `Authorization: Bearer ` header, answers in JSON, and starts with `/v1`.
## How the data is organized
Prices that apply to any industry. Today: **Commodities** — dairy prices published by the USDA, daily to monthly.
Data about the companies and products inside one industry. Today: **CPG** (consumer packaged goods).
Industry data is grouped by industry first, then by kind of data:
| Industry | Data set | What it tells you |
| -------- | --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| CPG | [**Branded food**](/industry-data/cpg/branded-food) | What's in a packaged food: ingredients, nutrition, serving, barcode, maker. |
| CPG | [**D2C › Shopify**](/industry-data/cpg/d2c/shopify) | What brands selling direct to consumers list online, and at what price: store profile, products, variants, collections. |
The Shopify data covers online stores in every industry. Pass `industry=cpg` when you search stores to keep only consumer packaged goods brands.
## First call
List every commodity series Orbbit publishes:
```bash theme={null}
curl --request GET \
--url https://api.orbbit.co/v1/commodities \
--header 'authorization: Bearer YOUR_API_KEY'
```
Continue with the [Quickstart](/quickstart), or open the **API Reference** tab to try any endpoint in the browser.
## What lives where
| If you want to… | Go to |
| ----------------------------------- | --------------------------------- |
| Make your first call | [Quickstart](/quickstart) |
| Get and use an API key | [Authentication](/authentication) |
| Understand an error | [Errors](/errors) |
| Work through an AI coding assistant | [AI agents](/ai-agents) |
| Look up an exact parameter or field | The **API Reference** tab |
## Where the data comes from
Every record carries a `source` field that names where it came from.
| `source` | Publisher | Data set |
| ----------- | ------------------------------------------------------------------ | ------------- |
| `usda-mars` | USDA Market News (CME dairy spot prices) | Commodities |
| `usda-mpr` | USDA Mandatory Price Reporting (dairy sales and milk class prices) | Commodities |
| `usda-fdc` | USDA FoodData Central, branded foods dataset | Branded food |
| `shopify` | Public storefronts of online stores built on Shopify | D2C › Shopify |
# Branded Food
Source: https://docs.orbbit.co/industry-data/cpg/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.
```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
}
```
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:
```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 }
]
}
```
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).
# Shopify
Source: https://docs.orbbit.co/industry-data/cpg/d2c/shopify
What direct-to-consumer brands list on their Shopify stores, and at what price: store profiles, products, variants, and collections.
Use this to see what other brands sell online and at what price — to size a market, compare your prices with competitors, or find brands that might buy your ingredients.
The data comes from the public storefronts of online stores built on Shopify. Every record has `source: "shopify"`.
The crawl covers stores in every industry, not just CPG. Pass `industry=cpg` when you search stores to keep only consumer packaged goods brands.
The API works from the store down: find stores, open one, then list its products and collections.
| Endpoint | What it does | Scope |
| --------------------------------- | -------------------------------------------- | ----------------------- |
| `GET /v1/stores` | Search stores with filters | `search-stores` |
| `GET /v1/stores/{id}` | Get one store's full profile | `get-store` |
| `GET /v1/stores/{id}/products` | List a store's products | `get-store-products` |
| `GET /v1/stores/{id}/collections` | List a store's collections | `get-store-collections` |
| `GET /v1/products/{id}` | Get one product with every variant and price | `get-product` |
## Search stores
Every filter is optional. When you pass several, a store must match all of them.
| Parameter | Type | Match | Description |
| ---------- | ------- | ----------------------- | ----------------------------------------------------------------------------------------------- |
| `domain` | string | Contains, ignoring case | The store's web address, such as `coffee`. |
| `name` | string | Contains, ignoring case | The store's name. |
| `industry` | string | Exact | Whether the store sells consumer packaged goods: `cpg`, `partial_cpg`, `not_cpg`, or `unknown`. |
| `category` | string | Exact | A product category the store sells in, such as `coffee_and_tea`. |
| `limit` | integer | — | Rows per page, default `50`, at most 200. Above 200 is served as 200. |
| `cursor` | string | — | The `next_cursor` from the previous page. |
### Your first search: find food and drink brands
```bash Request theme={null}
curl --request GET \
--url 'https://api.orbbit.co/v1/stores?industry=cpg&category=coffee_and_tea&limit=20' \
--header 'authorization: Bearer YOUR_API_KEY'
```
```json Response theme={null}
{
"data": [
{
"id": "shopify_store_01k3a1b2c3d4e5f6g7h8j9k0mn",
"domain": "example-coffee.com",
"name": "Example Coffee Co.",
"country": "US",
"industry": "cpg",
"category": "coffee_and_tea",
"product_count": 84,
"variant_count": 212,
"min_price": 7.5,
"median_price": 18,
"max_price": 129,
"crawled_at": "2026-08-31T00:00:00.000Z",
"source": "shopify"
}
],
"next_cursor": null
}
```
Values are illustrative.
### Understanding the response
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.
* `category` is the one category the store sells most of. A store can sell in several; `GET /v1/stores/{id}` shows the full mix.
* `product_count` and `variant_count` count what the store lists. A variant is one buyable version of a product, such as a size or flavor.
* `min_price`, `median_price`, and `max_price` summarize the store's variant prices, in the store's own currency.
* `crawled_at` is when Orbbit last read the store. Use it to judge how fresh the numbers are.
## Get a store's full profile
```bash Request theme={null}
curl --request GET \
--url https://api.orbbit.co/v1/stores/shopify_store_01k3a1b2c3d4e5f6g7h8j9k0mn \
--header 'authorization: Bearer YOUR_API_KEY'
```
```json Response theme={null}
{
"data": {
"id": "shopify_store_01k3a1b2c3d4e5f6g7h8j9k0mn",
"domain": "example-coffee.com",
"name": "Example Coffee Co.",
"industry": "cpg",
"category": "coffee_and_tea",
"shopify_domain": "example-coffee.myshopify.com",
"description": "Small-batch coffee roasted in Portland.",
"city": "Portland",
"province": "Oregon",
"currency": "USD",
"published_products_count": 84,
"common_crawl": {
"release": "CC-MAIN-2026-33",
"harmonic_rank": 1843221,
"host_count": 3
},
"categories": [
{ "category": "coffee_and_tea", "product_count": 71, "share": 0.845 },
{ "category": "soft_drinks_and_refreshments", "product_count": 13, "share": 0.155 }
]
}
}
```
Response trimmed for clarity. Values are illustrative. The profile has every field a search returns, plus:
* `currency` — the currency every price in this store is in.
* `categories` — every category the store sells in, with the share of its products in each, largest first.
* `common_crawl` — how prominent the store is on the web, from the public Common Crawl web index. A lower `harmonic_rank` means more of the web links to the store.
## List a store's products
Products are paged. Each product carries its price range and main image; open one product to see every variant.
```bash Request theme={null}
curl --request GET \
--url 'https://api.orbbit.co/v1/stores/shopify_store_01k3a1b2c3d4e5f6g7h8j9k0mn/products?limit=50' \
--header 'authorization: Bearer YOUR_API_KEY'
```
```json Response theme={null}
{
"data": [
{
"id": "shopify_product_01k3a9x8w7v6u5t4s3r2q1p0nm",
"title": "House Blend, Whole Bean",
"handle": "house-blend",
"vendor": "Example Coffee Co.",
"product_type": "Coffee",
"category": "coffee_and_tea",
"sub_category": "coffee",
"tags": ["medium-roast", "whole-bean"],
"image": {
"src": "https://cdn.shopify.com/s/files/1/0000/0000/products/house-blend.jpg",
"width": 1200,
"height": 1200
},
"price": { "min": 18, "max": 54, "currency": "USD" },
"variant_count": 3,
"published_at": "2025-03-14T17:02:11.000Z",
"source": "shopify"
}
],
"next_cursor": null
}
```
Values are illustrative.
## Get one product
`GET /v1/products/{id}` returns everything in the list row, plus the full description, every image, and every variant with its own price.
```bash theme={null}
curl --request GET \
--url https://api.orbbit.co/v1/products/shopify_product_01k3a9x8w7v6u5t4s3r2q1p0nm \
--header 'authorization: Bearer YOUR_API_KEY'
```
```json Response (variants only) theme={null}
{
"data": {
"id": "shopify_product_01k3a9x8w7v6u5t4s3r2q1p0nm",
"store_id": "shopify_store_01k3a1b2c3d4e5f6g7h8j9k0mn",
"variants": [
{
"id": "shopify_variant_01k3aa0b1c2d3e4f5g6h7j8k9mnp",
"title": "12 oz",
"sku": "HB-12",
"price": 18,
"compare_at_price": null,
"grams": 340,
"available": true,
"option1": "12 oz",
"option2": null,
"option3": null,
"position": 1,
"image_src": null
}
]
}
}
```
`compare_at_price` is the "was" price the store shows next to a sale price. When it's set and higher than `price`, the variant is on sale.
## List a store's collections
Collections are the merchant's own groupings of products, such as "Best sellers" or "Single origin". They show how a brand organizes and markets its range.
```bash theme={null}
curl --request GET \
--url https://api.orbbit.co/v1/stores/shopify_store_01k3a1b2c3d4e5f6g7h8j9k0mn/collections \
--header 'authorization: Bearer YOUR_API_KEY'
```
The response is a paged list of `{ id, title, handle, description, image, product_count, published_at, updated_at, source }`.
## Errors
An unknown store or product ID returns `404`:
```json 404 — unknown store theme={null}
{
"error": {
"type": "not_found",
"message": "Unknown store: shopify_store_01k3a1b2c3d4e5f6g7h8j9k0mn"
}
}
```
See [Errors](/errors) for every other error.
## Store fields
Returned by `GET /v1/stores` and `GET /v1/stores/{id}`.
| Field | Type | Description |
| --------------- | -------------- | ----------------------------------------------------------------------------------------------- |
| `id` | string | Orbbit's ID for the store. Starts with `shopify_store_`. |
| `domain` | string | The store's web address, such as `example-coffee.com`. |
| `name` | string or null | The store's name. |
| `country` | string or null | The country the store is based in, as a two-letter code. |
| `industry` | string or null | Whether the store sells consumer packaged goods: `cpg`, `partial_cpg`, `not_cpg`, or `unknown`. |
| `category` | string or null | The category the store sells most of. |
| `product_count` | number or null | How many products the store lists. |
| `variant_count` | number or null | How many variants — sizes, flavors, and so on — across all products. |
| `min_price` | number or null | The lowest variant price, in the store's currency. |
| `median_price` | number or null | The middle variant price. |
| `max_price` | number or null | The highest variant price. |
| `crawled_at` | string or null | When Orbbit last read the store, as an ISO 8601 timestamp. |
| `source` | string | Always `shopify`. |
### Profile-only fields
`GET /v1/stores/{id}` also returns:
| Field | Type | Description |
| ---------------------------- | -------------- | ----------------------------------------------------------------------------- |
| `shopify_domain` | string or null | The store's `myshopify.com` address. |
| `description` | string or null | The store's own description of itself. |
| `city` | string or null | The store's city. |
| `province` | string or null | The store's state or province. |
| `currency` | string or null | The currency the store prices in, such as `USD`. |
| `published_products_count` | number or null | How many products the store says it has published. |
| `common_crawl.release` | string or null | The Common Crawl web index release the ranking came from. |
| `common_crawl.harmonic_rank` | number or null | The store's rank by how much of the web links to it. Lower is more prominent. |
| `common_crawl.host_count` | number or null | How many web hosts under the store's domain the crawl found. |
| `categories[].category` | string | A category the store sells in. |
| `categories[].product_count` | number | How many of its products are in that category. |
| `categories[].share` | number | That count as a share of all its products, from 0 to 1. |
## Product fields
Returned by `GET /v1/stores/{id}/products` and `GET /v1/products/{id}`.
| Field | Type | Description |
| ---------------- | -------------- | ------------------------------------------------------------ |
| `id` | string | Orbbit's ID for the product. Starts with `shopify_product_`. |
| `title` | string or null | The product name. |
| `handle` | string or null | The product's name in the store's web address. |
| `vendor` | string or null | The brand or maker the store lists. |
| `product_type` | string or null | The store's own label for the kind of product. |
| `category` | string or null | The product's category. |
| `sub_category` | string or null | A narrower category within `category`. |
| `tags` | string\[] | The store's tags on the product. |
| `image` | object or null | The main image: `src`, `width`, `height`. |
| `price.min` | number or null | The lowest variant price. |
| `price.max` | number or null | The highest variant price. |
| `price.currency` | string or null | The currency of both prices. |
| `variant_count` | number | How many variants the product has. |
| `published_at` | string or null | When the store first published the product. |
| `source` | string | Always `shopify`. |
### Single-product fields
`GET /v1/products/{id}` also returns:
| Field | Type | Description |
| ----------- | -------------- | ----------------------------------------------------- |
| `store_id` | string | The store that sells the product. |
| `body_text` | string or null | The product description, as plain text. |
| `images` | array | Every image: `src`, `width`, `height`. |
| `variants` | array | Every variant. See [Variant fields](#variant-fields). |
## Variant fields
| Field | Type | Description |
| ------------------- | --------------- | --------------------------------------------------------------- |
| `id` | string | Orbbit's ID for the variant. Starts with `shopify_variant_`. |
| `title` | string or null | The variant name, such as `12 oz`. |
| `sku` | string or null | The store's stock-keeping code. |
| `price` | number or null | The current price. |
| `compare_at_price` | number or null | The "was" price shown beside a sale price. |
| `grams` | number or null | The shipping weight in grams. |
| `available` | boolean or null | Whether the variant can be bought right now. |
| `option1`–`option3` | string or null | The values that set this variant apart, such as size or flavor. |
| `position` | number or null | The variant's order on the product page. |
| `image_src` | string or null | The variant's own image, when it has one. |
## Collection fields
Returned by `GET /v1/stores/{id}/collections`.
| Field | Type | Description |
| --------------- | -------------- | ------------------------------------------------------------------ |
| `id` | string | Orbbit's ID for the collection. Starts with `shopify_collection_`. |
| `title` | string or null | The collection name. |
| `handle` | string or null | The collection's name in the store's web address. |
| `description` | string or null | The store's description of the collection. |
| `image` | object or null | The collection image: `src`, `alt`. |
| `product_count` | number or null | How many products the collection holds. |
| `published_at` | string or null | When the store published the collection. |
| `updated_at` | string or null | When the store last changed the collection. |
| `source` | string | Always `shopify`. |
## Validation rules
| Rule | Behavior |
| --------------- | ---------------------------------------------------------------------- |
| Filters combine | Several filters mean a store must match all of them. |
| Empty filter | `?name=` with no text is the same as leaving it out. |
| `limit` | A whole number of at least 1. Above 200 is served as 200, not refused. |
| Order | Results are sorted by `id`, so paging is stable. |
| Unknown ID | Any `{id}` that doesn't exist returns `404`. |
## Summary
| Endpoint | Scope | Response | Paged | Errors |
| --------------------------------- | ----------------------- | ------------------------------------- | ----- | -------------------------- |
| `GET /v1/stores` | `search-stores` | `{ data: [store], next_cursor }` | Yes | `400`, `401`, `403` |
| `GET /v1/stores/{id}` | `get-store` | `{ data: store profile }` | No | `401`, `403`, `404` |
| `GET /v1/stores/{id}/products` | `get-store-products` | `{ data: [product], next_cursor }` | Yes | `400`, `401`, `403`, `404` |
| `GET /v1/stores/{id}/collections` | `get-store-collections` | `{ data: [collection], next_cursor }` | Yes | `400`, `401`, `403`, `404` |
| `GET /v1/products/{id}` | `get-product` | `{ data: product }` | No | `401`, `403`, `404` |
## What to do next
* **Try it live** — [Search stores](/api-reference/shopify/search-stores), [Get a store](/api-reference/shopify/get-a-store), [List store products](/api-reference/shopify/list-store-products), [List store collections](/api-reference/shopify/list-store-collections), and [Get a product](/api-reference/shopify/get-a-product).
* **See how this fits with packaged-food data** — read the [CPG overview](/industry-data/cpg/overview).
# CPG Overview
Source: https://docs.orbbit.co/industry-data/cpg/overview
How brands, products, and prices fit together in consumer packaged goods, and which data set answers which question.
CPG — consumer packaged goods — is everything sold in a package to shoppers: food, drinks, snacks, personal care, household goods. Orbbit's CPG data answers two questions about a brand: **what it makes**, and **what it sells online, and for how much**.
## How the pieces fit
A CPG brand buys ingredients, makes a packaged product, and sells it — in stores, to wholesalers, or straight to consumers online. Each data set covers one part of that path.
| Question | Data set | What you get |
| --------------------------------------------------- | ----------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| What does it cost to make? | [Commodities](/market-data/commodities) (Market data) | The market price of raw ingredients such as butter, cheese, and milk. Applies to any industry, which is why it lives under Market data. |
| What's in the product? | [Branded food](/industry-data/cpg/branded-food) | The label of a packaged food: ingredients, nutrition, serving size, barcode, and who makes it. |
| What does the brand sell online, and at what price? | [D2C › Shopify](/industry-data/cpg/d2c/shopify) | A brand's own online store: its profile, every product and variant with its price, and how it groups products into collections. |
D2C means direct to consumer: the brand sells from its own website instead of through a retailer.
## Putting them together
The data sets share words you can match on — a brand name, an ingredient, a category — so you can connect them in your own code. For example:
* **Ingredient exposure.** Search [Branded food](/industry-data/cpg/branded-food) for products whose ingredients contain `butter`, then pull butter prices from [Commodities](/market-data/commodities) to see how the market price of that ingredient has moved.
* **Price positioning.** Search [D2C › Shopify](/industry-data/cpg/d2c/shopify) stores in the `coffee_and_tea` category and compare their `median_price` to see where a brand sits against its peers.
There is no shared ID that links a packaged food in Branded food to the same item in a Shopify store. Matching across the two is done by brand or product name in your own code, and won't always find a match.
## Where the data comes from
| Data set | `source` | Publisher |
| ------------- | ---------- | ---------------------------------------------------- |
| Branded food | `usda-fdc` | USDA FoodData Central, submitted by the brand owners |
| D2C › Shopify | `shopify` | Public storefronts of online stores built on Shopify |
# Commodities
Source: https://docs.orbbit.co/market-data/commodities
Market prices for raw ingredients, straight from the USDA: find a series in the catalog, then pull its prices by date.
Use this when you need the price history of a raw ingredient — to track input costs, check a supplier's quote against the market, or feed a forecast.
The Commodities API is two endpoints used together. First you search the catalog to find the series you want. Then you ask for that series' prices by date.
| Step | Endpoint | Scope |
| ---- | ---------------------------- | ---------------------- |
| 1 | `GET /v1/commodities` | `search-commodities` |
| 2 | `GET /v1/commodities/prices` | `get-commodity-prices` |
## What a series is
A series is one number a USDA report publishes over time — for example, "the daily closing price of Grade AA butter on the CME spot market, in dollars per pound". Each series has a `slug`: a readable, permanent ID such as `butter-cme-spot-close-daily`.
Orbbit publishes a fixed catalog of series that it checks by hand. You never see USDA's raw internal IDs, and a slug never changes meaning. The full list is in the [series catalog](#series-catalog) below.
## Search the catalog
`GET /v1/commodities` lists the series in the catalog, grouped by commodity.
| Parameter | Type | Required | Description |
| ----------- | ------ | -------- | -------------------------------------------------------------------------------------------------------------------- |
| `commodity` | string | No | Keep only series whose commodity name or slug contains this text, ignoring case. Leave it out for the whole catalog. |
```bash Request theme={null}
curl --request GET \
--url 'https://api.orbbit.co/v1/commodities?commodity=cheese' \
--header 'authorization: Bearer YOUR_API_KEY'
```
```json Response theme={null}
{
"data": [
{
"commodity": "Cheese",
"series": [
{
"slug": "cheese-block-cme-spot-close-daily",
"spec": "40 pound Block",
"market": "CME spot call, Chicago",
"measure": "close_price",
"unit": "USD/lb",
"frequency": "daily",
"source": "usda-mars",
"report": "CME Group Daily Cash Trading",
"first_observed_on": "2019-01-02",
"last_observed_on": "2026-09-22"
},
{
"slug": "cheese-barrel-cme-spot-close-daily",
"spec": "Barrels",
"market": "CME spot call, Chicago",
"measure": "close_price",
"unit": "USD/lb",
"frequency": "daily",
"source": "usda-mars",
"report": "CME Group Daily Cash Trading",
"first_observed_on": "2019-01-02",
"last_observed_on": "2026-09-22"
}
]
}
]
}
```
Response trimmed for clarity. Values are illustrative.
Use `first_observed_on` and `last_observed_on` to see how far back a series goes and how fresh it is before you ask for prices.
## Get prices
`GET /v1/commodities/prices` returns dated prices for one or more series.
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ----------------------------------------------------------------------------------- |
| `series` | string | Yes | One or more slugs, comma-separated. At most 100. |
| `from` | string | No | First date to include, as `YYYY-MM-DD`. Leave it out to start at the first reading. |
| `to` | string | No | Last date to include, as `YYYY-MM-DD`. Leave it out to run to the latest reading. |
```bash Request theme={null}
curl --request GET \
--url 'https://api.orbbit.co/v1/commodities/prices?series=butter-cme-spot-close-daily&from=2026-09-18&to=2026-09-22' \
--header 'authorization: Bearer YOUR_API_KEY'
```
```json Response theme={null}
{
"data": [
{
"slug": "butter-cme-spot-close-daily",
"unit": "USD/lb",
"points": [
{ "date": "2026-09-18", "value": 2.5125 },
{ "date": "2026-09-21", "value": 2.5 },
{ "date": "2026-09-22", "value": 2.4875 }
]
}
]
}
```
Values are illustrative.
### Understanding the response
* `data` has one entry per slug you asked for, in the order you asked.
* `unit` tells you how to read `value` — `USD/lb` is dollars per pound, `USD/cwt` is dollars per hundred pounds.
* `points` is in date order. Days with no reading, such as weekends for a daily series, are simply absent.
* `value` is exactly the number USDA published, with no rounding. CME prices, for example, move in quarter-cents and keep all four decimal places.
* A range with no readings returns the series with an empty `points` array, not an error.
## Compare several series in one call
Pass several slugs to line up prices side by side. This request compares the daily CME block and barrel cheese prices over the same week.
```bash theme={null}
curl --request GET \
--url 'https://api.orbbit.co/v1/commodities/prices?series=cheese-block-cme-spot-close-daily,cheese-barrel-cme-spot-close-daily&from=2026-09-15&to=2026-09-19' \
--header 'authorization: Bearer YOUR_API_KEY'
```
If any slug is not in the catalog, the whole request fails with `400` and the message names the unknown slug — so a typo never silently drops a series.
```json 400 — unknown slug theme={null}
{
"error": {
"type": "invalid_request",
"message": "Unknown series: cheese-cme-spot-close-daily"
}
}
```
## Series catalog
These are all the series you can pass to `GET /v1/commodities/prices`. Call `GET /v1/commodities` for the live list, including each series' first and last date.
### CME spot market (source `usda-mars`)
Prices from the CME Group's daily spot trading session in Chicago, as reported by USDA Market News. Unit: `USD/lb`.
| Product | Spec | Daily close | Weekly average | Monthly average |
| --------------- | -------------- | -------------------------------------- | ----------------------------------------- | ------------------------------------------ |
| Butter | Grade AA | `butter-cme-spot-close-daily` | `butter-cme-spot-average-weekly` | `butter-cme-spot-average-monthly` |
| Cheese | 40 pound Block | `cheese-block-cme-spot-close-daily` | `cheese-block-cme-spot-average-weekly` | `cheese-block-cme-spot-average-monthly` |
| Cheese | Barrels | `cheese-barrel-cme-spot-close-daily` | `cheese-barrel-cme-spot-average-weekly` | `cheese-barrel-cme-spot-average-monthly` |
| Nonfat Dry Milk | Grade A | `nonfat-dry-milk-cme-spot-close-daily` | `nonfat-dry-milk-cme-spot-average-weekly` | `nonfat-dry-milk-cme-spot-average-monthly` |
| Dry Whey | Extra Grade | `dry-whey-cme-spot-close-daily` | `dry-whey-cme-spot-average-weekly` | `dry-whey-cme-spot-average-monthly` |
### Manufacturer sales prices (source `usda-mpr`)
Weekly average prices manufacturers actually received, from the USDA's National Dairy Products Sales Report. Unit: `USD/lb`.
| Product | Spec | Slug |
| --------------- | ------------------------- | ------------------------------------ |
| Butter | Grade AA | `butter-sales-price-weekly` |
| Cheese | 40 pound Block, Cheddar | `cheese-block-sales-price-weekly` |
| Cheese | 500 pound Barrel, Cheddar | `cheese-barrel-sales-price-weekly` |
| Nonfat Dry Milk | — | `nonfat-dry-milk-sales-price-weekly` |
| Dry Whey | — | `dry-whey-sales-price-weekly` |
### Milk class prices (source `usda-mpr`)
Monthly minimum prices for raw milk set by the Federal Milk Marketing Orders. Unit: `USD/cwt` (dollars per hundred pounds).
| Spec | Slug |
| ----------------------------- | ------------------------------ |
| Class I, All Markets Combined | `milk-class-i-price-monthly` |
| Class II | `milk-class-ii-price-monthly` |
| Class III | `milk-class-iii-price-monthly` |
| Class IV | `milk-class-iv-price-monthly` |
## Series fields
Returned by `GET /v1/commodities`, inside `data[].series[]`.
| Field | Type | Description |
| ------------------- | -------------- | ------------------------------------------------------------------------------------------- |
| `slug` | string | The series ID. Pass it to `GET /v1/commodities/prices`. |
| `spec` | string or null | The grade or package, as the report states it — for example `Grade AA` or `40 pound Block`. |
| `market` | string | Where the price is formed — for example `CME spot call, Chicago`. |
| `measure` | string | The report's own name for the number, such as `close_price`. |
| `unit` | string | How to read `value`: `USD/lb` or `USD/cwt`. |
| `frequency` | string | How often a new reading appears: `daily`, `weekly`, or `monthly`. |
| `source` | string | Who publishes the data: `usda-mars` or `usda-mpr`. |
| `report` | string | The USDA report title — for example `CME Group Daily Cash Trading`. |
| `first_observed_on` | string or null | Date of the earliest reading, `YYYY-MM-DD`. |
| `last_observed_on` | string or null | Date of the latest reading, `YYYY-MM-DD`. |
Each series is grouped under its `commodity` name (for example `Cheese`), so one commodity can hold several series.
## Price fields
Returned by `GET /v1/commodities/prices`, inside `data[]`.
| Field | Type | Description |
| ---------------- | ------ | --------------------------------- |
| `slug` | string | The series you asked for. |
| `unit` | string | How to read each `value`. |
| `points` | array | Readings in date order. |
| `points[].date` | string | The reading's date, `YYYY-MM-DD`. |
| `points[].value` | number | The price, exactly as published. |
## Validation rules
| Rule | Behavior |
| --------------------- | ----------------------------------------------------------------------------------------- |
| `series` is required | Leaving it out returns `400`. |
| At most 100 slugs | More returns `400`. |
| Every slug must exist | One unknown slug fails the whole request with `400 Unknown series: `. |
| Dates | `from` and `to` must be real calendar days written `YYYY-MM-DD`; `2026-02-30` is refused. |
| Date order | `from` later than `to` returns `400`. |
| Both dates included | A reading dated exactly `from` or `to` is returned. |
| Empty filter | `?commodity=` with no text is the same as leaving it out. |
## Summary
| Detail | `GET /v1/commodities` | `GET /v1/commodities/prices` |
| ---------- | ----------------------------------- | ------------------------------------ |
| Scope | `search-commodities` | `get-commodity-prices` |
| Parameters | `commodity` | `series`, `from`, `to` |
| Response | `{ data: [{ commodity, series }] }` | `{ data: [{ slug, unit, points }] }` |
| Paged | No | No |
| Errors | `400`, `401`, `403` | `400`, `401`, `403` |
## What to do next
* **Try it live** — [Search commodity series](/api-reference/commodities/search-commodity-series) and [Get commodity prices](/api-reference/commodities/get-commodity-prices).
* **Handle errors** — see [Errors](/errors).
* **Let your AI assistant do it** — see [AI agents](/ai-agents).
# Connect Orbbit Data to Your AI Assistant
Source: https://docs.orbbit.co/mcp-server
Add Orbbit's data connector to Claude or Claude Code so your assistant can look up and call Orbbit endpoints for you.
Orbbit Data has its own connector, so you can ask an AI assistant for commodity, branded-food, and store data in plain words. The assistant finds the right endpoint, calls it with your account, and answers from the result.
It uses MCP (Model Context Protocol), the standard way AI tools plug into outside sources. This is a different connector from the [docs connector](/ai-agents): that one lets an assistant read these pages, while this one fetches Orbbit's data.
Connector address: `https://api.orbbit.co/mcp`
Your console's **MCP** page shows the same address with a copy button.
## Claude (web, desktop, mobile)
1. In Claude, open **Customize** → **Connectors** → **Add** → **Add custom connector**.
2. Name it `Orbbit Data`, paste the connector address, click **Add**, then **Connect**.
3. Sign in to Orbbit and click **Allow**.
The assistant can now call every endpoint your account can.
## Claude Code
Run this, then sign in to Orbbit and click **Allow** when your browser opens:
```bash theme={null}
claude mcp add --transport http orbbit-data https://api.orbbit.co/mcp
```
Connect with one of your [API keys](/authentication) instead of signing in:
```bash theme={null}
claude mcp add --transport http orbbit-data https://api.orbbit.co/mcp \
--header "Authorization: Bearer orbbit_data_YOUR_KEY"
```
The assistant can only call the endpoints that key is scoped to. Revoking the key cuts the connection off.
## What the assistant can do
The connector gives the assistant three tools, which it uses in this order:
| Tool | What it does |
| ------------------- | --------------------------------------------------------------------- |
| `list-endpoints` | Lists the endpoints this connection is allowed to call. |
| `describe-endpoint` | Shows one endpoint's parameters, so the assistant knows what to send. |
| `call-endpoint` | Calls the endpoint and returns exactly what the API would return. |
Every call goes through the same API as a direct request with your key, so the answer matches what you'd get from the [API Reference](/api-reference/introduction).
# Quickstart
Source: https://docs.orbbit.co/quickstart
Get an API key and pull your first commodity prices in under five minutes.
This walkthrough takes you from no key to a year of daily butter prices. Every step is one request.
Sign in to the Orbbit console and open **API Keys**. Click **New Key**, give it a **Name**, and under **Scope** tick the endpoints it may call. For this walkthrough, tick **Search Commodities** and **Get Commodity Prices**, then click **Create**.
The console shows the full key once. Copy it now — it starts with `orbbit_data_`. See [Authentication](/authentication) for how keys and their permissions work.
Ask the catalog which butter series exist. The `commodity` filter matches any part of the commodity name or the series ID, ignoring case.
```bash theme={null}
curl --request GET \
--url 'https://api.orbbit.co/v1/commodities?commodity=butter' \
--header 'authorization: Bearer YOUR_API_KEY'
```
Each series in the response has a `slug` — its ID. Pick `butter-cme-spot-close-daily`, the daily closing price on the CME spot market.
```json theme={null}
{
"data": [
{
"commodity": "Butter",
"series": [
{
"slug": "butter-cme-spot-close-daily",
"spec": "Grade AA",
"market": "CME spot call, Chicago",
"measure": "close_price",
"unit": "USD/lb",
"frequency": "daily",
"source": "usda-mars",
"report": "CME Group Daily Cash Trading",
"first_observed_on": "2019-01-02",
"last_observed_on": "2026-09-22"
}
]
}
]
}
```
Pass the slug to the prices endpoint with a date range. Both dates are included.
```bash theme={null}
curl --request GET \
--url 'https://api.orbbit.co/v1/commodities/prices?series=butter-cme-spot-close-daily&from=2025-09-01&to=2026-08-31' \
--header 'authorization: Bearer YOUR_API_KEY'
```
```json theme={null}
{
"data": [
{
"slug": "butter-cme-spot-close-daily",
"unit": "USD/lb",
"points": [
{ "date": "2025-09-02", "value": 2.1875 },
{ "date": "2025-09-03", "value": 2.195 }
]
}
]
}
```
Response trimmed for clarity. Each point is one trading day, in date order.
## What to do next
* **Compare several series at once** — pass up to 100 slugs, comma-separated, to [Get commodity prices](/api-reference/commodities/get-commodity-prices).
* **Look up a packaged food** — see [Search branded foods](/api-reference/branded-food/search-branded-foods).
* **Browse D2C brands** — see [Search stores](/api-reference/shopify/search-stores); add `industry=cpg` for consumer packaged goods brands.
* **Handle errors** — see [Errors](/errors) for every error your code should expect.
* **Let your AI assistant do it** — see [AI agents](/ai-agents).