​

Nutrition API

​

API Endpoints

• POST /nutrition_records - Upload food images for AI-powered nutritional analysis
• GET /nutrition_records - Retrieve a list of nutrition records
• GET /nutrition_records/ - Retrieve a specific nutrition record by ID

​

Getting Started

1. Obtain an API key from the Spike Team
2. Configure authentication using HMAC or client token method
3. Upload base64-encoded food images using the POST endpoint
4. Retrieve results either synchronously or via webhook notifications

​

Key Features

​

AI-Powered Analysis

• Advanced computer vision for food identification
• LANGUAL standard terminology for precise ingredient classification
• Machine learning models for accurate nutritional calculations

​

Flexible Processing

• Asynchronous processing (recommended) - Returns immediately with background processing
• Synchronous processing - Waits for complete analysis before returning results
• Webhook notifications for real-time status updates

​

Comprehensive Data

• 29 nutritional fields from basic macros to detailed micronutrients
• Ingredient breakdown with per-item nutritional analysis
• Nutri-Score rating (A-E European scale)
• Localized results with country and language support

​

Technical Requirements

​

Image Specifications

• Minimum size: 512×512 pixels
• Maximum size: 10MB when base64-encoded
• Supported formats: JPEG, PNG, WebP
• Input format: Base64-encoded string

​

Processing Workflow

1. Image Upload & Validation - System validates format compatibility
2. AI Model Processing - Multiple AI models analyze the image concurrently
3. Ingredient Identification - Foods identified using LANGUAL terminology
4. Nutritional Analysis - Detailed breakdown calculated per 100g/ml
5. Translation (optional) - Results translated to specified language
6. Storage - Results stored with configurable retention policies

​

Response Data

​

Basic Nutritional Fields

• Energy (kcal)
• Protein (g)
• Total Fat (g)
• Carbohydrates (g)

​

Extended Nutritional Data

• Fats: Saturated, polyunsaturated, monounsaturated, trans fats
• Micronutrients: Fiber, sugars, cholesterol
• Minerals: Sodium, potassium, calcium, iron, magnesium, phosphorus, zinc
• Vitamins: A, C, D, E, K, B-complex vitamins

​

Processing Status

• pending - Analysis has been queued
• processing - AI models are actively analyzing the image
• completed - Analysis finished successfully with results
• failed - Processing failed due to unidentifiable content or technical issues

​

Image Guidelines

1. Center the food - Capture the contents of the plate as the main subject
2. Fill the frame - Ensure the meal occupies the majority of the image
3. Remove distractions - Take off packaging or utensils before photographing
4. Clean background - Keep background clutter-free, include only the plate
5. Use proper lighting - Natural or bright lighting to capture food details clearly
6. Optimal angle - Slight angle to minimize items obscuring each other
7. Avoid filters - Don’t use filters that might alter the food’s appearance

​

Error Handling

​

Image Size Requirements

{
  "error": {
    "name": "Error",
    "status": 500,
    "faults": ["Image is too small"]
  }
}

​

No Food Detected

{
  "error": {
    "name": "Error", 
    "status": 400,
    "faults": ["No Food Detected"]
  }
}

​

Request Too Large

{
  "error": {
    "name": "BadRequestException",
    "status": 413,
    "faults": ["RequestEntityTooLarge"]
  }
}

​

Webhook Integration

• Security: All requests include HMAC SHA256 signature verification
• Header: x-body-signature contains the hex-encoded HMAC signature
• Payload: Complete nutrition record as JSON when analysis completes

​

Response Times