Route Risk Analysis

curl --request POST \
  --url https://api.vects.ai/risk-assessment/ \
  --header 'Content-Type: application/json' \
  --data '
{
  "routePoints": [
    {
      "routePoints[].lat": 123,
      "routePoints[].lng": 123,
      "routePoints[].timestamp": "<string>"
    }
  ],
  "riskTypes": [
    {}
  ],
  "timeWindow": {
    "timeWindow.start": "<string>",
    "timeWindow.end": "<string>"
  },
  "resolution": "<string>"
}
'

{
  "200": {},
  "400": {},
  "401": {},
  "429": {},
  "500": {},
  "riskPoints": [
    {
      "riskPoints[].lat": 123,
      "riskPoints[].lng": 123,
      "riskPoints[].weight": 123,
      "riskPoints[].riskLevel": "<string>",
      "riskPoints[].threats": [
        {}
      ]
    }
  ],
  "summary": {
    "summary.overallRisk": "<string>",
    "summary.maxRiskWeight": 123,
    "summary.averageRisk": 123,
    "summary.totalDistance": 123,
    "summary.highRiskSegments": 123
  },
  "threats": [
    {
      "threats[].id": "<string>",
      "threats[].type": "<string>",
      "threats[].severity": "<string>",
      "threats[].description": "<string>",
      "threats[].location": {},
      "threats[].timeframe": {},
      "threats[].confidence": 123
    }
  ],
  "recommendations": [
    {
      "recommendations[].type": "<string>",
      "recommendations[].priority": "<string>",
      "recommendations[].description": "<string>",
      "recommendations[].alternativeRoute": [
        {}
      ]
    }
  ]
}

POST

risk-assessment

Route Risk Analysis

curl --request POST \
  --url https://api.vects.ai/risk-assessment/ \
  --header 'Content-Type: application/json' \
  --data '
{
  "routePoints": [
    {
      "routePoints[].lat": 123,
      "routePoints[].lng": 123,
      "routePoints[].timestamp": "<string>"
    }
  ],
  "riskTypes": [
    {}
  ],
  "timeWindow": {
    "timeWindow.start": "<string>",
    "timeWindow.end": "<string>"
  },
  "resolution": "<string>"
}
'

{
  "200": {},
  "400": {},
  "401": {},
  "429": {},
  "500": {},
  "riskPoints": [
    {
      "riskPoints[].lat": 123,
      "riskPoints[].lng": 123,
      "riskPoints[].weight": 123,
      "riskPoints[].riskLevel": "<string>",
      "riskPoints[].threats": [
        {}
      ]
    }
  ],
  "summary": {
    "summary.overallRisk": "<string>",
    "summary.maxRiskWeight": 123,
    "summary.averageRisk": 123,
    "summary.totalDistance": 123,
    "summary.highRiskSegments": 123
  },
  "threats": [
    {
      "threats[].id": "<string>",
      "threats[].type": "<string>",
      "threats[].severity": "<string>",
      "threats[].description": "<string>",
      "threats[].location": {},
      "threats[].timeframe": {},
      "threats[].confidence": 123
    }
  ],
  "recommendations": [
    {
      "recommendations[].type": "<string>",
      "recommendations[].priority": "<string>",
      "recommendations[].description": "<string>",
      "recommendations[].alternativeRoute": [
        {}
      ]
    }
  ]
}

Overview

The Route Risk Analysis API evaluates potential threats and hazards along a specified path or route. This endpoint analyzes various risk factors including geopolitical events, environmental hazards, infrastructure conditions, and real-time threat data to provide comprehensive risk assessments.

Authentication

curl -X POST "https://api.vects.ai/risk-assessment/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json"

This endpoint supports anonymous access for basic risk assessments, though authenticated requests receive more detailed analysis.

Request Body

routePoints

array

required

Array of coordinate points defining the route to analyze. Each point should contain latitude and longitude.

Show routePoints structure

routePoints[].lat

number

required

Latitude coordinate (-90 to 90)

routePoints[].lng

number

required

Longitude coordinate (-180 to 180)

routePoints[].timestamp

string

Optional ISO 8601 timestamp for time-specific risk analysis

riskTypes

array

Optional array of specific risk types to analyze. If not provided, all risk types are assessed.Available types: geopolitical, environmental, infrastructure, crime, traffic, weather

timeWindow

object

Optional time window for temporal risk analysis

Show timeWindow properties

timeWindow.start

string

Start time in ISO 8601 format

timeWindow.end

string

End time in ISO 8601 format

resolution

string

default:"medium"

Analysis resolution: low, medium, high

low: Basic risk assessment with major threats only
medium: Standard assessment with moderate detail
high: Comprehensive assessment with fine-grained analysis

Example Requests

curl -X POST "https://api.vects.ai/risk-assessment/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "routePoints": [
      {"lat": 37.7749, "lng": -122.4194},
      {"lat": 37.7849, "lng": -122.4094},
      {"lat": 37.7949, "lng": -122.3994}
    ]
  }'

Response

riskPoints

array

Array of risk assessment points along the route

Show riskPoints structure

riskPoints[].lat

number

Latitude coordinate of the risk point

riskPoints[].lng

number

Longitude coordinate of the risk point

riskPoints[].weight

number

Risk weight/score (0.0 to 1.0, where 1.0 is highest risk)

riskPoints[].riskLevel

string

Categorical risk level: low, medium, high, critical

riskPoints[].threats

array

Array of specific threats identified at this location

summary

object

Overall route risk summary

Show summary properties

summary.overallRisk

string

Overall route risk level: low, medium, high, critical

summary.maxRiskWeight

number

Highest risk weight found along the route

summary.averageRisk

number

Average risk weight across all points

summary.totalDistance

number

Total route distance in kilometers

summary.highRiskSegments

integer

Number of high-risk segments identified

threats

array

Detailed threat information

Show threats structure

threats[].id

string

Unique threat identifier

threats[].type

string

Threat category

threats[].severity

string

Threat severity: low, medium, high, critical

threats[].description

string

Human-readable threat description

threats[].location

object

Geographic location of the threat

threats[].timeframe

object

Temporal information about the threat

threats[].confidence

number

Confidence score for the threat assessment (0.0 to 1.0)

recommendations

array

Risk mitigation recommendations

Show recommendations structure

recommendations[].type

string

Recommendation type: route_change, timing_adjustment, precaution, equipment

recommendations[].priority

string

Priority level: low, medium, high, urgent

recommendations[].description

string

Detailed recommendation description

recommendations[].alternativeRoute

array

Alternative route coordinates (if applicable)

Example Response

{
  "riskPoints": [
    {
      "lat": 37.7749,
      "lng": -122.4194,
      "weight": 0.2,
      "riskLevel": "low",
      "threats": ["minor_traffic_congestion"]
    },
    {
      "lat": 37.7849,
      "lng": -122.4094,
      "weight": 0.7,
      "riskLevel": "high",
      "threats": ["active_protest", "road_closure"]
    },
    {
      "lat": 37.7949,
      "lng": -122.3994,
      "weight": 0.3,
      "riskLevel": "medium",
      "threats": ["construction_zone"]
    }
  ],
  "summary": {
    "overallRisk": "high",
    "maxRiskWeight": 0.7,
    "averageRisk": 0.4,
    "totalDistance": 15.2,
    "highRiskSegments": 1
  },
  "threats": [
    {
      "id": "threat_001",
      "type": "geopolitical",
      "severity": "high",
      "description": "Large protest gathering with potential for civil unrest",
      "location": {
        "lat": 37.7849,
        "lng": -122.4094,
        "radius": 500
      },
      "timeframe": {
        "start": "2024-01-15T13:00:00Z",
        "end": "2024-01-15T17:00:00Z"
      },
      "confidence": 0.85
    },
    {
      "id": "threat_002",
      "type": "infrastructure",
      "severity": "medium",
      "description": "Road construction causing lane closures",
      "location": {
        "lat": 37.7949,
        "lng": -122.3994,
        "radius": 200
      },
      "timeframe": {
        "start": "2024-01-15T08:00:00Z",
        "end": "2024-01-15T18:00:00Z"
      },
      "confidence": 0.95
    }
  ],
  "recommendations": [
    {
      "type": "route_change",
      "priority": "high",
      "description": "Consider alternative route to avoid protest area",
      "alternativeRoute": [
        {"lat": 37.7749, "lng": -122.4194},
        {"lat": 37.7799, "lng": -122.4144},
        {"lat": 37.7949, "lng": -122.3994}
      ]
    },
    {
      "type": "timing_adjustment",
      "priority": "medium",
      "description": "Delay travel until after 17:00 to avoid peak protest activity"
    },
    {
      "type": "precaution",
      "priority": "medium",
      "description": "Monitor real-time traffic updates for construction delays"
    }
  ]
}

Risk Types

Geopolitical Risks

Political demonstrations and protests
Civil unrest and conflicts
Border tensions and restrictions
Government instability

Environmental Risks

Natural disasters (earthquakes, floods, storms)
Extreme weather conditions
Environmental hazards (pollution, radiation)
Climate-related threats

Infrastructure Risks

Road closures and construction
Bridge and tunnel conditions
Public transportation disruptions
Utility outages

Crime Risks

High crime areas
Recent criminal activity
Security incidents
Theft and violence hotspots

Traffic Risks

Congestion patterns
Accident-prone areas
Rush hour impacts
Special event traffic

Weather Risks

Current weather conditions
Weather forecasts
Seasonal weather patterns
Extreme weather alerts

Status Codes

200

Risk analysis completed successfully

400

Bad Request

Invalid route points or request parameters

401

Unauthorized

Invalid or missing API key (for authenticated features)

429

Too Many Requests

Rate limit exceeded

500

Internal Server Error

Server error during risk analysis

Error Response

{
  "error": "Invalid route points: Route must contain at least 2 points",
  "code": "INVALID_ROUTE_POINTS",
  "details": {
    "field": "routePoints",
    "min_points": 2,
    "provided_points": 1
  }
}

Integration Examples

JavaScript/Web

async function analyzeRoute(routePoints) {
    const response = await fetch('https://api.vects.ai/risk-assessment/', {
        method: 'POST',
        headers: {
            'Authorization': 'Api-Key YOUR_API_KEY',
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            routePoints: routePoints,
            resolution: 'high'
        })
    });
    
    const riskData = await response.json();
    
    // Visualize risk points on map
    riskData.riskPoints.forEach(point => {
        addRiskMarker(point.lat, point.lng, point.weight);
    });
}

Python

import requests

def analyze_route_risk(route_points, api_key):
    url = "https://api.vects.ai/risk-assessment/"
    headers = {
        "Authorization": f"Api-Key {api_key}",
        "Content-Type": "application/json"
    }
    data = {
        "routePoints": route_points,
        "resolution": "high"
    }
    
    response = requests.post(url, headers=headers, json=data)
    return response.json()

# Example usage
route = [
    {"lat": 37.7749, "lng": -122.4194},
    {"lat": 37.7849, "lng": -122.4094}
]
risk_analysis = analyze_route_risk(route, "your_api_key")

Next Steps

Explore Radius Risk Analysis for area-based assessments
Learn about Urban Mobility MARL for dynamic risk modeling
Check out Simulation APIs for scenario planning

Server Messages Radius Risk Analysis

​Overview

​Authentication

​Request Body

​Example Requests

​Response

​Example Response

​Risk Types

​Geopolitical Risks

​Environmental Risks

​Infrastructure Risks

​Crime Risks

​Traffic Risks

​Weather Risks

​Status Codes

​Error Response

​Integration Examples

​JavaScript/Web

​Python

​Next Steps

Overview

Authentication

Request Body

Example Requests

Response

Example Response

Risk Types

Geopolitical Risks

Environmental Risks

Infrastructure Risks

Crime Risks

Traffic Risks

Weather Risks

Status Codes

Error Response

Integration Examples

JavaScript/Web

Python

Next Steps