Events API

The Events API allows you to work with individual driving events detected in videos. This page documents both the REST API endpoints and the corresponding SDK methods.

Event Structure

Each detected event contains the following information:

{
  "time": 23.5,
  "type": "Traffic Violation",
  "severity": "medium",
  "description": "Running stop sign",
  "dmv_rule": "CVC 22450(a)",
  "metrics": {
    "confidence": 0.92,
    "speed": 15.7,
    "distance": 3.2,
    "acceleration": -2.1
  },
  "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...",
  "frame_idx": 705,
  "objects_involved": [
    {
      "type": "vehicle",
      "position": {"x": 450, "y": 320},
      "bbox": {"x1": 420, "y1": 300, "x2": 480, "y2": 340},
      "track_id": 3
    },
    {
      "type": "stop_sign",
      "position": {"x": 520, "y": 280},
      "bbox": {"x1": 510, "y1": 270, "x2": 530, "y2": 290},
      "track_id": 7
    }
  ]
}

Get Video Events

Retrieve events detected in a specific video.

SDK Method

# Get all events from a video
events = client.video.get_video_events("video_id")

# Filter events by severity
high_severity_events = client.video.get_video_events(
    video_id="video_id",
    severity="high"
)

# Filter events by type
traffic_violations = client.video.get_video_events(
    video_id="video_id",
    event_type="Traffic Violation"
)

HTTP Request

GET /api/video/{video_id}/events

Headers:

X-API-Key: your_api_key

Query Parameters:

firebase_collection_name (string, required): Collection name (default: “videos”)
severity (string, optional): Filter by severity (“low”, “medium”, “high”)
event_type (string, optional): Filter by event type (“Traffic Violation”, “Safety Alert”, etc.)

Response:

[
  {
    "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...
]

Get All Events

Retrieve events across all videos, with optional filtering.

SDK Method

The current SDK doesn’t provide a direct method for this endpoint, but you can implement it by retrieving events from individual videos and combining the results.

HTTP Request

GET /api/events

Headers:

X-API-Key: your_api_key

Query Parameters:

firebase_collection_name (string, required): Collection name (default: “videos”)
severity (string, optional): Filter by severity (“low”, “medium”, “high”)
event_type (string, optional): Filter by event type (“Traffic Violation”, “Safety Alert”, etc.)
date_from (string, optional): Filter by date range start (ISO format)
date_to (string, optional): Filter by date range end (ISO format)
limit (integer, optional): Maximum number of events to return (default: 100)
offset (integer, optional): Pagination offset (default: 0)

Response:

{
  "total_count": 235,
  "returned_count": 100,
  "offset": 0,
  "events": [
    {
      "video_id": "uuid-string-1",
      "time": 23.5,
      "type": "Traffic Violation",
      "severity": "medium",
      "description": "Running stop sign",
      // Additional event details...
    },
    // Additional events...
  ]
}

Get Specific Event

Retrieve a specific event by its ID.

SDK Method

The current SDK doesn’t provide a direct method for this endpoint.

HTTP Request

GET /api/events/{event_id}

Headers:

X-API-Key: your_api_key

Query Parameters:

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

Response:

{
  "event_id": "event-uuid",
  "video_id": "video-uuid",
  "time": 23.5,
  "type": "Traffic Violation",
  "severity": "medium",
  "description": "Running stop sign",
  "dmv_rule": "CVC 22450(a)",
  "metrics": {
    "confidence": 0.92,
    "speed": 15.7,
    "distance": 3.2,
    "acceleration": -2.1
  },
  "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...",
  "frame_idx": 705,
  "objects_involved": [
    // Objects involved in the event
  ]
}

Get Event Thumbnail

Retrieve a thumbnail image for a specific event.

SDK Method

The current SDK doesn’t provide a direct method for this endpoint.

HTTP Request

GET /api/events/{event_id}/thumbnail

Headers:

X-API-Key: your_api_key

Query Parameters:

firebase_collection_name (string, required): Collection name (default: “videos”)
size (string, optional): Thumbnail size (“small”, “medium”, “large”, default: “medium”)
format (string, optional): Image format (“jpg”, “png”, default: “jpg”)

Response: Binary image data with appropriate content type header.

Get Event Clip

Extract a short video clip centered around a specific event.

SDK Method

The current SDK doesn’t provide a direct method for this endpoint.

HTTP Request

GET /api/events/{event_id}/clip

Headers:

X-API-Key: your_api_key

Query Parameters:

firebase_collection_name (string, required): Collection name (default: “videos”)
duration (number, optional): Clip duration in seconds (default: 10)
before_ratio (number, optional): Portion of clip before the event (0-1, default: 0.3)
format (string, optional): Video format (“mp4”, “webm”, default: “mp4”)
resolution (string, optional): Video resolution (“original”, “720p”, “480p”, default: “720p”)

Response: Binary video data with appropriate content type header.

Similar Events

Find events similar to a specific event.

SDK Method

The current SDK doesn’t provide a direct method for this endpoint.

HTTP Request

GET /api/events/{event_id}/similar

Headers:

X-API-Key: your_api_key

Query Parameters:

firebase_collection_name (string, required): Collection name (default: “videos”)
limit (integer, optional): Maximum number of similar events to return (default: 10)
min_similarity (number, optional): Minimum similarity score (0-1, default: 0.7)
search_scope (string, optional): Search scope (“all”, “user”, default: “user”)

Response:

{
  "reference_event": {
    "event_id": "event-uuid",
    "video_id": "video-uuid",
    "time": 23.5,
    "type": "Traffic Violation",
    "description": "Running stop sign"
  },
  "similar_events": [
    {
      "event_id": "event-uuid-2",
      "video_id": "video-uuid-2",
      "time": 45.2,
      "type": "Traffic Violation",
      "description": "Running stop sign",
      "similarity_score": 0.92,
      "thumbnail_url": "https://api.nomadicml.com/thumbnails/event-uuid-2.jpg"
    },
    // Additional similar events...
  ]
}

Update Event

Add custom information to an event.

SDK Method

The current SDK doesn’t provide a direct method for this endpoint.

HTTP Request

PATCH /api/events/{event_id}

Headers:

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

Request Body:

{
  "notes": "Driver was distracted by phone",
  "tags": ["distracted", "training_needed"],
  "custom_fields": {
    "driver_id": "D12345",
    "instructor_feedback": "Needs to focus more on surroundings"
  }
}

Response:

{
  "event_id": "event-uuid",
  "message": "Event updated successfully",
  "updated_fields": ["notes", "tags", "custom_fields"]
}

Event Statistics

Get statistics about events across all videos.

SDK Method

The current SDK doesn’t provide a direct method for this endpoint.

HTTP Request

GET /api/events/statistics

Headers:

X-API-Key: your_api_key

Query Parameters:

firebase_collection_name (string, required): Collection name (default: “videos”)
date_from (string, optional): Filter by date range start (ISO format)
date_to (string, optional): Filter by date range end (ISO format)

Response:

{
  "total_events": 235,
  "by_type": {
    "Traffic Violation": 98,
    "Safety Alert": 56,
    "Drive Quality": 72,
    "DMV Compliance": 9
  },
  "by_severity": {
    "low": 123,
    "medium": 85,
    "high": 27
  },
  "most_common": {
    "description": "Failure to maintain lane position",
    "count": 37
  },
  "most_severe": {
    "description": "Near collision with pedestrian",
    "count": 3
  },
  "trends": {
    "improving": ["Complete stops", "Turn signal usage"],
    "worsening": ["Following distance", "Speed management"]
  }
}

Flag Event

Report an issue with event detection.

SDK Method

The current SDK doesn’t provide a direct method for this endpoint.

HTTP Request

POST /api/events/{event_id}/flag

Headers:

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

Request Body:

{
  "reason": "false_positive",
  "description": "This is not a stop sign violation, it's a yield sign"
}

Response:

{
  "event_id": "event-uuid",
  "message": "Event flagged successfully",
  "flag_id": "flag-uuid",
  "status": "under_review"
}

Event Types Reference

Get a reference list of all event types and their definitions.

SDK Method

The current SDK doesn’t provide a direct method for this endpoint.

HTTP Request

GET /api/events/types

Headers:

X-API-Key: your_api_key

Response:

{
  "types": [
    {
      "id": "traffic_violation",
      "name": "Traffic Violation",
      "description": "Events that violate traffic laws or regulations",
      "subtypes": [
        {
          "id": "stop_sign",
          "name": "Stop Sign Violation",
          "description": "Failure to come to a complete stop at a stop sign",
          "dmv_rules": ["CVC 22450(a)"]
        },
        // Additional subtypes...
      ]
    },
    // Additional event types...
  ]
}

Error Handling

The Events API returns the same error structure as the other APIs:

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

Common error codes specific to the Events API:

event_not_found: The requested event doesn’t exist
invalid_event_parameters: Invalid parameters for event operation
clip_generation_failed: Failed to generate event clip
thumbnail_generation_failed: Failed to generate event thumbnail

Next Steps

Advanced Integrations

Integrate event data with your systems

Best Practices

Learn best practices for working with events

API Reference

​Events API

​Event Structure

​Get Video Events

​SDK Method

​HTTP Request

​Get All Events

​SDK Method

​HTTP Request

​Get Specific Event

​SDK Method

​HTTP Request

​Get Event Thumbnail

​SDK Method

​HTTP Request

​Get Event Clip

​SDK Method

​HTTP Request

​Similar Events

​SDK Method

​HTTP Request

​Update Event

​SDK Method

​HTTP Request

​Event Statistics

​SDK Method

​HTTP Request

​Flag Event

​SDK Method

​HTTP Request

​Event Types Reference

​SDK Method

​HTTP Request

​Error Handling

​Next Steps

Advanced Integrations

Best Practices

Events API

Event Structure

Get Video Events

SDK Method

HTTP Request

Get All Events

SDK Method

HTTP Request

Get Specific Event

SDK Method

HTTP Request

Get Event Thumbnail

SDK Method

HTTP Request

Get Event Clip

SDK Method

HTTP Request

Similar Events

SDK Method

HTTP Request

Update Event

SDK Method

HTTP Request

Event Statistics

SDK Method

HTTP Request

Flag Event

SDK Method

HTTP Request

Event Types Reference

SDK Method

HTTP Request

Error Handling

Next Steps