Nutrition API Implementation Guide
This guide provides complete implementation details and best practices for integrating the Nutrition API into your applications. For detailed API specifications and data types, refer to the API Reference.Authentication: The code examples in this guide focus on the nutrition analysis functionality. For authentication implementation details, see the Authentication documentation. You’ll need to add Bearer token into the Authorization header to all API requests.
API Endpoints
The Nutrition API provides three main endpoints for managing nutrition records:POST /nutrition_records
— Upload food images for AI-powered nutritional analysisGET /nutrition_records
— Retrieve a list of nutrition recordsGET /nutrition_records/{id}
— Retrieve a specific nutrition record by ID
Image Preparation
For optimal image capture guidelines, see the Image Guidelines in the API overview.POST Request Body
Processing Modes
The processing mode is controlled by thewait_on_process
parameter. The API supports two processing modes, each suited for a different use case:
Asynchronous Processing
Returns immediately and processes the image in the background. Ideal for user-facing applications where immediate feedback is important. See the Asynchronous Processing Guide for complete implementation details, webhook configuration, and code examples.Synchronous Processing
Waits for complete analysis before responding. Best for batch processing, server-to-server integrations, or when you can handle longer response times: Request:Analysis Modes
precise
(default): Uses advanced AI models for the highest accuracy and detailed analysisfast
: Uses optimized models for quicker processing with good accuracy
Localization
Providecountry_code
and language_code
for region-specific analysis:
- Region-specific food recognition
- Usage of local nutritional databases
- Translated ingredient names and descriptions
Including Optional Data
Control what data is included in the analysis:Selection of Nutritional Fields
You can control which nutritional fields are included in the analysis:include_nutrition_fields
is omitted or empty, only four basic fields are included by default:
carbohydrate_g
energy_kcal
fat_total_g
protein_g
Response Body
Processing Status
Analysis of the nutrition record progresses through these states:- pending — Analysis has been queued
- processing — an AI model is actively analyzing the image
- completed — Analysis finished successfully with results
- failed — Processing failed due to unidentifiable content or technical issues
status
field.
status
field with values completed
or failed
only. Always handle different response statuses in your application logic.
Error Scenarios
Processing Failures
These occur when the API successfully receives your request but the AI analysis fails. The response will have HTTP 200 status with"status": "failed"
.
When status
is failed
, check the failure_reason
field for specific details:
- Unidentifiable food items: Image contains non-food objects or unclear food items
- Poor image quality: Blurry, dark, or low-resolution images
Request Errors
These occur when there’s an issue with the request itself, returning non-200 HTTP status codes before analysis begins. For HTTP status code errors (400, 401, 422, etc.) and general API error handling, see the Error Handling documentation.Nutrition Fields and Units
The names of nutrition fields are always lowercase and include units as suffix. Nutrition fields are not translated.Retrieving Results
Getting Results
For asynchronous processing, use webhooks for real-time notifications. See the Asynchronous Processing Guide for complete webhook implementation details. If webhooks are not yet available, you can check status using theGET /nutrition_records/{id}
endpoint.
Best Practices
1. Choose the Right Processing Mode
- Asynchronous: For user-facing applications, mobile apps, and when you want immediate feedback
- Synchronous: For batch processing, server-to-server integrations, and when you can handle longer response times
2. Implement Proper Error Handling
- Handle network errors gracefully
- Provide meaningful error messages to users
- Implement retry logic for transient failures
Code Examples
Here are complete implementation examples in multiple programming languages:POST /nutrition_records
API Reference.