​

Best Practices

​

Video Capture Guidelines

​

Camera Placement

• Front View: Mount the camera at the center of the windshield for the best perspective
• Height: Position at approximately eye level (4-5 feet above ground)
• Angle: Slight downward tilt (10-15 degrees) to capture the road ahead
• Clear View: Ensure the camera has an unobstructed view of the road

​

Video Quality

• Resolution: Minimum 720p (1280×720), recommended 1080p (1920×1080)
• Frame Rate: Minimum 24 fps, recommended 30 fps
• Bitrate: Minimum 4 Mbps, recommended 8 Mbps
• Format: MP4 with H.264 encoding works best
• Lighting: Ensure adequate lighting for clear visibility
• Weather: Be aware that heavy rain, snow, or fog can affect analysis accuracy

​

Recording Length

• Optimal Duration: 5-20 minutes per video for best performance
• Split Longer Drives: For drives over 30 minutes, consider splitting into multiple videos
• Context: Include enough time before and after key events for proper context

​

Data Management

​

Video Organization

• Consistent Naming: Use a consistent naming scheme for videos (e.g., YYYY-MM-DD_Driver_Route.mp4)
• Metadata: Add relevant metadata when uploading (driver, vehicle, route, etc.)
• Tagging: Use tags to categorize videos by purpose, location, or scenario
• Archiving: Develop a policy for archiving older videos to manage storage

​

Analysis Retention

• Short-term (30 days): Recent training sessions or evaluations
• Medium-term (90 days): Trend analysis and pattern recognition
• Long-term (1+ years): Historical comparisons and compliance documentation

​

API Usage Optimization

​

Rate Limiting

• Respect Limits: Stay within the published rate limits (60 requests/minute, 10,000/day)
• Batch Operations: Combine multiple operations into fewer API calls when possible
• Implement Backoff: Use exponential backoff when receiving rate limit errors
• Monitor Usage: Track your API usage to avoid unexpected throttling

​

Efficient Requests

• Pagination: Use pagination parameters for large result sets
• Filtering: Apply server-side filters to reduce data transfer
• Field Selection: Request only the fields you need
• Compression: Use gzip compression for larger responses

# Example of efficient API usage
import requests

API_BASE = "https://api-prod.nomadicml.com/api"
API_KEY = "your_api_key"

headers = {
    "X-API-Key": API_KEY,
    "Accept-Encoding": "gzip"  # Request compression
}

# Use pagination and filters
params = {
    "limit": 100,  # Page size
    "offset": 0,   # Starting point
    "event_type": "Traffic Violation",  # Filter by type
    "fields": "video_id,time,type,severity,description"  # Select only needed fields
}

all_events = []
while True:
    response = requests.get(
        f"{API_BASE}/events",
        headers=headers,
        params=params
    )
    
    data = response.json()
    events = data["events"]
    
    if not events:
        break
        
    all_events.extend(events)
    params["offset"] += params["limit"]  # Move to next page

​

Caching

• TTL-based Caching: Cache responses with appropriate time-to-live values
• Conditional Requests: Use etags or last-modified headers for validation
• Local Storage: Store reference data locally (e.g., event types, DMV rules)

​

SDK Best Practices

​

Environment Setup

• Virtual Environments: Use virtual environments to manage dependencies
• Version Pinning: Pin the SDK version in your requirements.txt file
• Configuration Management: Use environment variables or secure configuration files for API keys

# Example environment setup
python -m venv nomadic-env
source nomadic-env/bin/activate  # Or nomadic-env\Scripts\activate on Windows
pip install nomadicml==0.1.0

​

Error Handling

from nomadicml import NomadicML
from nomadicml.exceptions import (
    AuthenticationError,
    VideoUploadError,
    AnalysisError,
    NomadicMLError
)

try:
    client = NomadicML(api_key="your_api_key")
    response = client.upload(url)
    response = client.analyze(
        response['video_id'],
        analysis_type="rapid_review",
        custom_event="Find all instances of ego vehicle straddling two lanes",
        custom_category="driving"
    )

    
except AuthenticationError:
    # Handle authentication issues
    print("Authentication failed - check your API key")
except VideoUploadError as e:
    # Handle upload-specific errors
    print(f"Upload failed: {e}")
except AnalysisError as e:
    # Handle analysis-specific errors
    print(f"Analysis failed: {e}")
except NomadicMLError as e:
    # Handle all other SDK errors
    print(f"An error occurred: {e}")
except Exception as e:
    # Handle unexpected errors
    print(f"Unexpected error: {e}")

​

Analysis Interpretation

​

Context Matters

• Environmental Factors: Consider weather, traffic, and road conditions
• Vehicle Limitations: Account for vehicle capabilities and characteristics
• Driving Purpose: Interpret events in the context of the driving purpose (training, testing, etc.)

​

Severity Assessment

• Low Severity: Opportunities for improvement, not immediate safety concerns
• Medium Severity: Notable issues that should be addressed
• High Severity: Critical safety concerns requiring immediate attention

​

Trend Analysis

• Frequency Analysis: Track event frequency over time
• Location Patterns: Identify problematic locations or scenarios
• Driver Comparison: Compare performance across different drivers
• Before/After: Measure the impact of training or interventions

​

Performance Optimization

​

Batch Processing

• Process videos in batches during off-peak hours
• Use background workers for upload and analysis tasks
• Implement queuing systems for large workloads

​

Resource Management

• Compress videos before upload to reduce bandwidth
• Clean up temporary files after processing
• Implement TTL (time-to-live) policies for stored videos

​

Security Best Practices

​

API Key Management

• Rotation: Rotate API keys regularly (every 90 days recommended)
• Scope Limitation: Use the minimum required permissions
• Secure Storage: Store API keys in secure credential stores, not in code
• Monitoring: Monitor API key usage for unusual patterns

​

Data Security

• Encryption: Ensure data is encrypted in transit and at rest
• Access Control: Implement proper access controls for videos and analysis data
• Data Minimization: Only store the data you need
• Retention Policy: Implement data retention and deletion policies

​

Audit Trail

• Log all video uploads and deletions
• Track who accessed analysis results
• Record API key creation and revocation
• Monitor for suspicious activity

​

Next Steps