API Reference

Food Search

Search foods by name or brand with multi-word matching and relevance ranking. Results include complete nutrition data, per-100g macros, the nutrients array, and serving metadata, and only foods with complete macro data are returned. An empty query returns common and popular foods.

curl "https://calorieapiadmin.com/api/v1/search/foods?q=chicken+breast&match_mode=all" \
  -H "X-API-Key: your_api_key_here"

Query parameters

qSearch query (min 2 characters; empty returns common foods)

limitResults per page, 1-100 (default: 30). Returned rows are capped by your plan’s foods-per-query limit (see pricing). k is accepted as an alias.

skipOffset for pagination (default: 0)

brandFilter by brand name (ILIKE)

brand_idFilter by brand ID

categoryFilter by category name (ILIKE)

category_idFilter by category ID

nutrient_idRequire this nutrient; use with min_amount / max_amount

min_amount / max_amountAmount range for nutrient_id (requires nutrient_id)

min_calories / max_caloriesMacro shortcut filters (also min/max protein, carbs, fat)

match_mode"any" (default) or "all", whether every word must match

verified_onlytrue to return only verified foods with curated macro data

{
  "data": [
    {
      "id": 12345,
      "name": "Apple, raw",
      "brand_name": null,
      "is_verified": true,
      "calories_100g": 52,
      "protein_100g": 0.3,
      "carbs_100g": 13.8,
      "fat_100g": 0.2,
      "fiber_100g": 2.4,
      "sugar_100g": 10.4,
      "nutrients": [
        { "nutrient_id": 106888, "nutrient_name": "Calories", "amount": 52 },
        { "nutrient_id": 106899, "nutrient_name": "Protein", "amount": 0.3 }
      ],
      "serving_size": 100,
      "serving_unit": "g",
      "default_portion": { "grams": 100, "label": "100 g" },
      "portions_count": 1,
      "meal": {
        "name": "Apple, raw",
        "calories": 52,
        "servings": 1,
        "macros": { "protein": 0.3, "carbs": 13.8, "fat": 0.2, "fiber": 2.4, "sugar": 10.4 }
      }
    }
  ],
  "total": 1,
  "skip": 0,
  "limit": 30
}

Verified portions

Verified foods expose real household servings from verified_portions. Search returns default_portion and portions_count, sets serving fields from that default, keeps nutrients/*_100g as per-100g baselines, and adds portion_nutrients plus meal scaled by default_portion.grams / 100. Full verified_portions lives on GET /api/v1/foods/{id}. For any other grams, use GET /api/v1/calc/portion or multiply amount_100g * grams / 100.

Lightweight catalog

For food metadata without nutrients, use GET /api/v1/catalog/foods. Page size is capped by your plan’s foods-per-query limit (see pricing). Single-food meta is GET /api/v1/catalog/foods/{id}. Taxonomy lists live at /catalog/brands, /catalog/categories, and /catalog/nutrients. Full nutrition detail remains on GET /api/v1/foods/{id}.

curl "https://calorieapiadmin.com/api/v1/catalog/foods?category=Dairy&limit=100" \
  -H "X-API-Key: your_api_key_here"

Public demo (no API key)

The same brand/category/nutrient filters are available on GET /api/v1/public/search/foods and GET /api/v1/public/catalog/* without an API key. Public demos are IP rate limited and use lower max limits (search/catalog foods max 10; taxonomy max 50). Use the /playground UI to try them.

curl "https://calorieapiadmin.com/api/v1/public/search/foods?q=yogurt&category=Dairy&limit=5"

How ranking works

Exact phrase at the start of the name ("chicken breast" matches "Chicken breast, raw") ranks first.
Exact phrase anywhere in the name ranks next.
All words present in any order, or most words for long queries, follows.
First word or any word present ranks last.

Autocomplete suggest

For typeahead UIs, the suggest endpoint returns lightweight results (id, name, brand_name) so you can render suggestions fast, then fetch full nutrition data with the food details endpoint after the user selects one. Debounce keystrokes in your client to conserve quota.

curl "https://calorieapiadmin.com/api/v1/search/suggest?q=chick&limit=10" \
  -H "X-API-Key: your_api_key_here"

Query parameters

qPrefix to autocomplete (min 1 character)

limitSuggestions to return, 1-20 (default: 15)

Frequently asked questions

How do I paginate through search results?

Use skip and limit together; the response envelope includes total, so you can compute page counts. limit accepts values up to 100, but the number of foods returned is capped by your plan (Free 20 by default, paid 100). See the pricing page for the live cap.

When should I use match_mode=all?

Use "all" when precision matters more than recall, for example matching a logged meal name exactly. The default "any" is better for exploratory search UIs.

What does verified_only do?

It restricts results to curated foods with complete, quality-checked macro data. Use it when data accuracy matters more than catalog coverage.