FAQ

Calorie API is a REST API for nutrition and food data: search, autocomplete, barcode lookup, and macro nutrients per 100g. It is designed for health, fitness, and meal-tracking applications.

Send your API key in the X-API-Key header, or use a JWT from the developer dashboard after signing in. Public demo search on the homepage is IP-rate-limited and does not require a key.

A free tier includes monthly request quotas for development. Paid plans increase rate limits and monthly quotas. See the pricing page for current limits.

Search supports multi-word queries, match_mode (any/all), verified-only filters, and relevance ranking aligned with verified foods and complete macro data.

Commercial production use requires a Plus or Enterprise plan. Send the header X-API-Usage-Type: commercial when your app is a commercial product. Free, Basic, and Core are for non-commercial development and personal use.

Use the skip and limit query parameters on GET /api/v1/search/foods. Responses are a JSON envelope with data, total, skip, and limit fields, so you can page through results. The limit accepts values up to 100 (default 30).

Barcode lookup checks the local food database first and automatically falls back to Open Food Facts. If neither source has the product, the API returns HTTP 404 with a "Food not found for barcode" message. Handle this by offering manual food search in your app.

Per-minute rate limits return HTTP 429 with X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers. Retry after the reset time with exponential backoff. Exceeding your monthly quota returns HTTP 402, and commercial-use or food-coverage violations return HTTP 403.

GET /api/v1/search/suggest?q={prefix} returns lightweight results (id, name, brand_name) for typeahead UIs, up to 20 items per request. Debounce keystrokes in your client and fetch full nutrition data with the food details endpoint after selection.

Yes. Pass the brand query parameter on /api/v1/search/foods to restrict results to a brand, and use the brands, categories, and nutrients reference endpoints to build filter UIs.

All endpoints return JSON. Food objects include per-100g macro values, a structured nutrients array, and serving metadata, so responses map directly to meal-logging data models.

Requests beyond your plan’s monthly quota return HTTP 402 with a "Monthly API quota exceeded" message until the next billing cycle. You can upgrade your plan from the dashboard at any time to raise the quota immediately.

Yes. Plans are billed through Stripe and managed from the developer dashboard: upgrades, downgrades, and cancellations take effect without contacting support.

Yes. The Free plan includes a monthly request quota intended for development, prototyping, and personal projects. Create an account, generate an API key, and start making requests.

If your product charges users, serves ads, or otherwise generates revenue, it is commercial use and requires a Plus or Enterprise plan with the X-API-Usage-Type: commercial header. Non-commercial development and personal tools can use Free, Basic, or Core.

The food database covers 4M+ foods spanning generic foods, branded products, and restaurant items, with barcode lookup extending coverage through Open Food Facts.

Verified foods are curated entries with complete, quality-checked macro data. Pass verified_only=true on search to restrict results to verified foods, useful when data accuracy matters more than coverage.

Yes. Every food returns macros normalized per 100g alongside a full nutrients array and serving metadata, so calorie and macro math is consistent across generic and branded foods.

UPC and EAN barcodes are supported via GET /api/v1/search/barcode/{upc}. Scans hit the local catalog first and fall back to Open Food Facts for broader product coverage.

Foods include a structured nutrients array with micronutrients when available, in addition to the guaranteed per-100g macro set (calories, protein, carbohydrates, fat).