Analysis API

The Analysis API provides detailed information about the video 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

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")

Method Parameters

Parameter	Type	Required	Description
`video_id`	string	Yes	ID of the video

Return Value

{
  "status": "analyzing",
  "video_id": "uuid-string",
  "quick_summary": {
    "status": "analyzing",
    "progress": 65,
    "stage": "event_detection",
    "estimated_time_remaining": 45
  },
  "metadata": {
    "filename": "example.mp4",
    "upload_time": "2023-03-15T14:30:00Z",
    "duration": 120.5,
    "frame_count": 3615,
    "fps": 30.0,
    "width": 1920,
    "height": 1080
  }
}

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”)

Get Full Analysis

Retrieve the complete analysis for a video.

SDK Method

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

Method Parameters

Parameter	Type	Required	Description
`video_id`	string	Yes	ID of the video

Return Value

{
  "video_id": "uuid-string",
  "status": "completed",
  "filename": "example.mp4",
  "upload_time": "2023-03-15T14:30:00Z",
  "metadata": {
    "duration": 120.5,
    "frame_count": 3615,
    "fps": 30.0,
    "width": 1920,
    "height": 1080,
    "source": "file"
  },
  "events": [
    {
      "time": 23.5,
      "type": "Traffic Violation",
      "severity": "medium",
      "description": "Running stop sign",
      "dmv_rule": "CVC 22450(a)",
      "metrics": {
        "confidence": 0.92,
        "speed": 15.7
      },
      "ai_analysis": "Vehicle approached stop sign at intersection and continued through without coming to a complete stop...",
      "recommendations": "Always come to a complete stop at stop signs, even if the intersection appears clear..."
    },
    // Additional events...
  ],
  "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
    }
  }
}

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”)

Wait for Analysis Completion

Wait for a video analysis to complete.

SDK Method

# Wait for analysis to complete with custom parameters
status = client.video.wait_for_analysis(
    video_id="video_id",
    timeout=600,  # Maximum wait time in seconds
    poll_interval=5  # Time between status checks in seconds
)

# Wait for multiple analyses to complete
results = client.video.wait_for_analyses(
    video_ids=["video_id_1", "video_id_2", "video_id_3"]
)

Method Parameters

Parameter	Type	Required	Description
`video_id`	string	Yes	ID of the video
`timeout`	integer	No	Maximum wait time in seconds (default: 600)
`poll_interval`	integer	No	Time between status checks in seconds (default: 5)

Return Value

For single video:

{
  "status": "completed",
  "video_id": "uuid-string",
  "quick_summary": { ... },
  "metadata": { ... }
}

For multiple videos:

{
  "video_id_1": { ... },  # Status object for first video
  "video_id_2": { ... },  # Status object for second video
  "video_id_3": { ... }   # Status object for third video
}

Analysis Status Codes

The analysis status can be one of the following:

Status	Description
`uploading`	Video is being uploaded
`uploading_failed`	Upload failed
`uploaded`	Upload completed
`processing`	Video is being processed
`analyzing`	Analysis is in progress
`completed`	Analysis completed
`failed`	Analysis failed
`not_found`	Video not found

Understanding Progress Information

The status response includes progress information:

"quick_summary": {
  "status": "analyzing",
  "progress": 65,  # Percentage complete
  "stage": "event_detection",
  "estimated_time_remaining": 45  # In seconds
}

The stage field can be one of:

preprocessing: Initial video processing
detection: Object detection
tracking: Object tracking
event_detection: Event detection
event_analysis: Event analysis
summarization: Final summary generation

Analysis Metrics

The analysis results include various metrics about the video:

General Metrics

safety_score: Overall safety rating (0-100)
dmv_compliance_score: Compliance with DMV rules (0-100)

Detailed Metrics

"metrics": {
  "average_speed": 28.7,          # Miles per hour
  "max_speed": 42.3,              # Miles per hour
  "hard_braking_count": 2,        # Number of hard braking events
  "sudden_acceleration_count": 1, # Number of sudden acceleration events
  "lane_deviation_count": 3,      # Number of lane deviations
  "complete_stops": 4,            # Number of complete stops
  "turn_signal_usage": 6          # Number of turn signal uses
}

Multiple Video Analyses

Get analysis results for multiple videos.

SDK Method

# Get analyses for multiple videos
analyses = client.video.get_video_analyses([
    "video_id_1", 
    "video_id_2"
])

Method Parameters

Parameter	Type	Required	Description
`video_ids`	list	Yes	List of video IDs

Return Value

[
  {
    "video_id": "video_id_1",
    "metadata": { ... },
    "events": [ ... ],
    "status": "success"
  },
  {
    "video_id": "video_id_2",
    "metadata": { ... },
    "events": [ ... ],
    "status": "success"
  }
]

Error Handling

The API returns standard HTTP status codes and the SDK raises specific exceptions:

APIError: General API errors
AnalysisError: Issues during video analysis
NomadicMLError: Base class for all SDK errors

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

Example error handling:

from nomadicml.exceptions import AnalysisError, NomadicMLError

try:
    analysis = client.video.get_video_analysis("video_id")
except AnalysisError as e:
    print(f"Analysis error: {e}")
except NomadicMLError as e:
    print(f"General error: {e}")

Using Analysis Results

Here’s a example of how to process and use the analysis results:

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

# Print video metadata
print(f"Video: {analysis['filename']}")
print(f"Duration: {analysis['metadata']['duration']} seconds")
print(f"Resolution: {analysis['metadata']['width']}x{analysis['metadata']['height']}")

# Print safety scores
print(f"Safety Score: {analysis['analysis']['safety_score']}")
print(f"DMV Compliance: {analysis['analysis']['dmv_compliance_score']}")

# Process events
for event in analysis['events']:
    print(f"\nEvent at {event['time']}s: {event['type']} ({event['severity']})")
    print(f"Description: {event['description']}")
    print(f"DMV Rule: {event['dmv_rule']}")
    
    # Print AI analysis if available
    if 'ai_analysis' in event:
        print(f"Analysis: {event['ai_analysis']}")

API Reference

Analysis API

Analysis API

Analysis Process

Get Analysis Status

SDK Method

Method Parameters

Return Value

HTTP Request

Get Full Analysis

SDK Method

Method Parameters

Return Value

HTTP Request

Wait for Analysis Completion

SDK Method

Method Parameters

Return Value

Analysis Status Codes

Understanding Progress Information

Analysis Metrics

General Metrics

Detailed Metrics

Multiple Video Analyses

SDK Method

Method Parameters

Return Value

Error Handling

Using Analysis Results

Next Steps

Events API

Custom Integrations

API Reference

​Analysis API

​Analysis Process

​Get Analysis Status

​SDK Method

​Method Parameters

​Return Value

​HTTP Request

​Get Full Analysis

​SDK Method

​Method Parameters

​Return Value

​HTTP Request

​Wait for Analysis Completion

​SDK Method

​Method Parameters

​Return Value

​Analysis Status Codes

​Understanding Progress Information

​Analysis Metrics

​General Metrics

​Detailed Metrics

​Multiple Video Analyses

​SDK Method

​Method Parameters

​Return Value

​Error Handling

​Using Analysis Results

​Next Steps

Events API

Custom Integrations

Analysis API

Analysis Process

Get Analysis Status

SDK Method

Method Parameters

Return Value

HTTP Request

Get Full Analysis

SDK Method

Method Parameters

Return Value

HTTP Request

Wait for Analysis Completion

SDK Method

Method Parameters

Return Value

Analysis Status Codes

Understanding Progress Information

Analysis Metrics

General Metrics

Detailed Metrics

Multiple Video Analyses

SDK Method

Method Parameters

Return Value

Error Handling

Using Analysis Results

Next Steps