Analysis API

The Analysis API provides detailed information about the analysis process and results. This page documents both the REST API endpoints and the corresponding SDK methods.

Analysis Process

The NomadicML analysis process involves several stages:

Video Processing: The video is prepared for analysis (decoding, frame extraction)
Object Detection: AI models identify and track objects in the video
Event Detection: The system identifies significant driving events
Context Analysis: Each event is analyzed in context
Report Generation: A comprehensive analysis is compiled

The API provides access to the results of this process and allows you to control certain aspects of the analysis.

Get Analysis Status

Check the current status of a video’s analysis.

SDK Method

# Get analysis status
status = client.video.get_video_status("video_id")

HTTP Request

GET /api/video/{video_id}/status

Headers:

X-API-Key: your_api_key

Query Parameters:

firebase_collection_name (string, required): Collection name (default: “videos”)

Response:

{
  "video_id": "uuid-string",
  "status": "analyzing",
  "metadata": {
    "visual_analysis": {
      "status": "analyzing",
      "progress": 65,
      "stage": "event_detection",
      "estimated_time_remaining": 45
    }
  }
}

Get Full Analysis

Retrieve the complete analysis for a video.

SDK Method

# Get complete analysis
analysis = client.video.get_video_analysis("video_id")

HTTP Request

GET /api/video/{video_id}/analysis

Headers:

X-API-Key: your_api_key

Query Parameters:

firebase_collection_name (string, required): Collection name (default: “videos”)

Response:

{
  "video_id": "uuid-string",
  "status": "completed",
  "filename": "example.mp4",
  "upload_time": "2025-03-15T14:30:00Z",
  "metadata": {
    "duration": 120.5,
    "frame_count": 3615,
    "fps": 30.0,
    "width": 1920,
    "height": 1080,
    "source": "file"
  },
  "events": [
    // Array of event objects
  ],
  "analysis": {
    "summary": "This video contains 5 notable events including 2 traffic violations...",
    "safety_score": 78,
    "dmv_compliance_score": 82,
    "context": {
      "road_type": "urban",
      "lighting_conditions": "daylight",
      "weather": "clear",
      "traffic_density": "moderate"
    },
    "metrics": {
      "average_speed": 28.7,
      "max_speed": 42.3,
      "hard_braking_count": 2,
      "sudden_acceleration_count": 1,
      "lane_deviation_count": 3
    }
  }
}

Get Analysis Summary

Get a condensed summary of the video analysis.

SDK Method

There is no direct SDK method for this specific endpoint. Use get_video_analysis() and extract the summary information.

HTTP Request

GET /api/video/{video_id}/summary

Headers:

X-API-Key: your_api_key

Query Parameters:

firebase_collection_name (string, required): Collection name (default: “videos”)

Response:

{
  "video_id": "uuid-string",
  "duration": 120.5,
  "event_count": 5,
  "event_types": {
    "Traffic Violation": 2,
    "Safety Alert": 1,
    "Drive Quality": 2
  },
  "severity_distribution": {
    "high": 1,
    "medium": 2,
    "low": 2
  },
  "safety_score": 78,
  "dmv_compliance_score": 82,
  "summary": "This video contains 5 notable events including 2 traffic violations..."
}

Get Video Metadata

Retrieve just the metadata of a video.

SDK Method

There is no direct SDK method for this specific endpoint. Use get_video_status() and extract the metadata.

HTTP Request

GET /api/video/{video_id}/metadata

Headers:

X-API-Key: your_api_key

Query Parameters:

firebase_collection_name (string, required): Collection name (default: “videos”)

Response:

{
  "video_id": "uuid-string",
  "filename": "example.mp4",
  "upload_time": "2025-03-15T14:30:00Z",
  "duration": 120.5,
  "frame_count": 3615,
  "fps": 30.0,
  "width": 1920,
  "height": 1080,
  "source": "file",
  "original_url": null,
  "title": "Example Video"
}

Analysis Settings

Control settings for video analysis.

SDK Method

Currently, the SDK does not provide a direct method for updating analysis settings. These must be specified during the upload or analysis request.

HTTP Request

PUT /api/video/{video_id}/analysis-settings

Headers:

X-API-Key: your_api_key
Content-Type: application/json

Request Body:

{
  "sensitivity": "standard",  // "low", "standard", "high"
  "focus": "general",  // "general", "safety", "dmv"
  "detection_threshold": 0.7,
  "include_metrics": true,
  "generate_recommendations": true
}

Response:

{
  "video_id": "uuid-string",
  "message": "Analysis settings updated",
  "settings": {
    "sensitivity": "standard",
    "focus": "general",
    "detection_threshold": 0.7,
    "include_metrics": true,
    "generate_recommendations": true
  }
}

Stop Analysis

Stop an ongoing analysis process.

SDK Method

# Stop analysis for a video
client.video.stop_analysis("video_id")

HTTP Request

POST /api/stop-analyze-video

Headers:

X-API-Key: your_api_key
Content-Type: application/x-www-form-urlencoded

Form Parameters:

video_id (string, required): ID of the video to stop analyzing

Response:

{
  "video_id": "uuid-string",
  "message": "Analysis stopped",
  "status": "stopped"
}

Get Analysis Metrics

Retrieve detailed metrics from the video analysis.

SDK Method

There is no direct SDK method for this specific endpoint. Use get_video_analysis() and extract the metrics information.

HTTP Request

GET /api/video/{video_id}/metrics

Headers:

X-API-Key: your_api_key

Query Parameters:

firebase_collection_name (string, required): Collection name (default: “videos”)

Response:

{
  "video_id": "uuid-string",
  "duration": 120.5,
  "metrics": {
    "driving": {
      "average_speed": 28.7,
      "max_speed": 42.3,
      "hard_braking_count": 2,
      "sudden_acceleration_count": 1,
      "lane_deviation_count": 3,
      "complete_stops": 4,
      "turn_signal_usage": 6
    },
    "safety": {
      "safety_score": 78,
      "close_following_instances": 2,
      "near_collision_count": 0,
      "distraction_indicators": 1
    },
    "compliance": {
      "dmv_compliance_score": 82,
      "traffic_sign_compliance": 0.85,
      "lane_discipline": 0.92,
      "speed_limit_compliance": 0.95
    }
  }
}

Compare Analysis

Compare the analysis results of two videos.

SDK Method

There is no direct SDK method for this endpoint, but you can implement comparison logic by retrieving analyses for multiple videos and comparing them programmatically.

HTTP Request

GET /api/compare-analysis

Headers:

X-API-Key: your_api_key

Query Parameters:

video_id_1 (string, required): ID of the first video
video_id_2 (string, required): ID of the second video
firebase_collection_name (string, required): Collection name (default: “videos”)

Response:

{
  "videos": [
    {
      "video_id": "uuid-string-1",
      "filename": "example1.mp4",
      "duration": 120.5
    },
    {
      "video_id": "uuid-string-2",
      "filename": "example2.mp4",
      "duration": 135.2
    }
  ],
  "comparison": {
    "event_counts": {
      "video_id_1": 5,
      "video_id_2": 7
    },
    "safety_scores": {
      "video_id_1": 78,
      "video_id_2": 82
    },
    "dmv_compliance_scores": {
      "video_id_1": 82,
      "video_id_2": 79
    },
    "common_events": [
      {
        "type": "Traffic Violation",
        "description": "Running stop sign",
        "video_1_time": 23.5,
        "video_2_time": 45.2,
        "similarity_score": 0.87
      }
    ],
    "unique_events": {
      "video_id_1": [
        {
          "time": 67.8,
          "type": "Safety Alert",
          "description": "Close following distance"
        }
      ],
      "video_id_2": [
        {
          "time": 12.3,
          "type": "Drive Quality",
          "description": "Hesitation at intersection"
        },
        {
          "time": 98.7,
          "type": "Traffic Violation",
          "description": "Improper lane change"
        }
      ]
    }
  }
}

Analysis Reports

Generate a formatted report of video analysis.

SDK Method

There is no direct SDK method for this endpoint.

HTTP Request

GET /api/video/{video_id}/report

Headers:

X-API-Key: your_api_key

Query Parameters:

firebase_collection_name (string, required): Collection name (default: “videos”)
format (string, optional): Report format (“pdf”, “html”, “json”, default: “pdf”)
include_thumbnails (boolean, optional): Include event thumbnails (default: true)
include_recommendations (boolean, optional): Include recommendations (default: true)

Response: For PDF/HTML formats, a binary file is returned with the appropriate content type. For JSON format, a structured report is returned:

{
  "video_id": "uuid-string",
  "report_type": "full_analysis",
  "generated_at": "2025-03-15T14:30:00Z",
  "metadata": {
    // Video metadata
  },
  "summary": {
    // Summary information
  },
  "events": [
    // Detailed event information
  ],
  "metrics": {
    // Detailed metrics
  },
  "recommendations": [
    // Recommendations based on analysis
  ]
}

Error Handling

The Analysis API returns the same error structure as the Video API:

{
  "error": true,
  "code": "error_code",
  "message": "Human-readable error message",
  "details": {
    // Additional error details if available
  }
}

Common error codes specific to the Analysis API:

analysis_not_found: The requested analysis doesn’t exist
analysis_in_progress: Analysis is still in progress
analysis_failed: Analysis failed to complete
invalid_analysis_parameters: Invalid analysis parameters provided

Next Steps

Events API

Work with detected events

Custom Integrations

Integrate analysis results with your systems

API Reference

​Analysis API

​Analysis Process

​Get Analysis Status

​SDK Method

​HTTP Request

​Get Full Analysis

​SDK Method

​HTTP Request

​Get Analysis Summary

​SDK Method

​HTTP Request

​Get Video Metadata

​SDK Method

​HTTP Request

​Analysis Settings

​SDK Method

​HTTP Request

​Stop Analysis

​SDK Method

​HTTP Request

​Get Analysis Metrics

​SDK Method

​HTTP Request

​Compare Analysis

​SDK Method

​HTTP Request

​Analysis Reports

​SDK Method

​HTTP Request

​Error Handling

​Next Steps

Events API

Custom Integrations

Analysis API

Analysis Process

Get Analysis Status

SDK Method

HTTP Request

Get Full Analysis

SDK Method

HTTP Request

Get Analysis Summary

SDK Method

HTTP Request

Get Video Metadata

SDK Method

HTTP Request

Analysis Settings

SDK Method

HTTP Request

Stop Analysis

SDK Method

HTTP Request

Get Analysis Metrics

SDK Method

HTTP Request

Compare Analysis

SDK Method

HTTP Request

Analysis Reports

SDK Method

HTTP Request

Error Handling

Next Steps