Nutrition API

Upload food images and receive detailed nutritional analysis powered by AI. The Nutrition API uses advanced computer vision and machine learning to identify ingredients, calculate nutritional values, and provide comprehensive food composition data.

API Endpoints

The Nutrition API provides three main endpoints for managing nutrition records:

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

Nutrition records progress through these states:
  • 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

For optimal analysis results, guide your users to:
  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

Common error scenarios include:

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

For asynchronous processing, configure webhook URLs to receive status updates:
  • 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

Response times typically range from 4–30 seconds depending on image complexity and the completeness of nutrition fields requested. Processing times may vary due to internal factors in AI analysis and nutritional information compilation.