Simulation Risk Analysis

Overview

The Simulation Risk Analysis API combines the power of text-to-3D simulation generation with comprehensive risk assessment capabilities. This endpoint creates realistic simulations while simultaneously analyzing potential threats, hazards, and safety concerns within the generated environment.

Authentication

curl -X POST "https://api.worldlens.co/api/v1/simulations/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json"

Request Body

prompt

string

required

Natural language description of the simulation scenario with risk considerations

risk_analysis

object

required

Risk analysis configuration

Show risk_analysis properties

risk_analysis.enabled

boolean

default:"true"

Enable integrated risk assessment

risk_analysis.types

array

Risk types to analyze: geopolitical, environmental, infrastructure, crime, traffic, weather

risk_analysis.resolution

string

default:"medium"

Analysis resolution: low, medium, high

risk_analysis.time_window

object

Time window for temporal risk analysis

risk_analysis.include_mitigation

boolean

default:"true"

Include risk mitigation recommendations

scenario_type

string

default:"general"

Scenario type: emergency_response, urban_planning, security_assessment, disaster_simulation, general

settings

object

Simulation settings (same as standard simulation API)

webhook_url

string

Optional webhook URL for completion notifications

Example Requests

curl -X POST "https://api.worldlens.co/api/v1/simulations/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Simulate a building fire evacuation in a 20-story office complex during peak hours with emergency responders arriving",
    "scenario_type": "emergency_response",
    "risk_analysis": {
      "enabled": true,
      "types": ["environmental", "infrastructure", "traffic"],
      "resolution": "high",
      "include_mitigation": true
    },
    "settings": {
      "max_agents": 500,
      "simulation_duration": 900,
      "environment_type": "indoor"
    }
  }'

Response

The response includes all standard simulation fields plus comprehensive risk analysis data:

simulation_id

string

Unique identifier for the created simulation

status

string

Current status: queued, processing, completed, failed

risk_assessment

object

Comprehensive risk analysis results

Show risk_assessment properties

risk_assessment.overall_risk_level

string

Overall risk level: low, medium, high, critical

risk_assessment.risk_score

number

Numerical risk score (0.0 to 1.0)

risk_assessment.risk_zones

array

Array of identified risk zones within the simulation

risk_assessment.threats

array

Detailed threat analysis

risk_assessment.vulnerabilities

array

Identified vulnerabilities in the scenario

risk_assessment.mitigation_strategies

array

Recommended risk mitigation strategies

safety_metrics

object

Safety and performance metrics

Show safety_metrics properties

safety_metrics.evacuation_time

number

Estimated evacuation time in seconds (for emergency scenarios)

safety_metrics.bottlenecks

array

Identified bottlenecks and congestion points

safety_metrics.capacity_utilization

number

Space/infrastructure capacity utilization (0.0 to 1.0)

safety_metrics.accessibility_score

number

Accessibility score for disabled individuals

recommendations

array

Actionable recommendations for improving safety and efficiency

Example Response

{
  "simulation_id": "sim_risk_abc123",
  "status": "completed",
  "created_at": "2024-01-15T10:30:00Z",
  "completed_at": "2024-01-15T10:38:15Z",
  "prompt": "Simulate a building fire evacuation in a 20-story office complex during peak hours",
  "scenario_type": "emergency_response",
  "risk_assessment": {
    "overall_risk_level": "high",
    "risk_score": 0.75,
    "risk_zones": [
      {
        "id": "zone_001",
        "type": "bottleneck",
        "location": {
          "floor": 15,
          "coordinates": [37.7749, -122.4194]
        },
        "risk_level": "critical",
        "description": "Stairwell congestion causing evacuation delays",
        "affected_agents": 45,
        "estimated_delay": 180
      },
      {
        "id": "zone_002",
        "type": "structural",
        "location": {
          "floor": 8,
          "coordinates": [37.7751, -122.4196]
        },
        "risk_level": "medium",
        "description": "Potential structural weakness near fire source",
        "confidence": 0.72
      }
    ],
    "threats": [
      {
        "id": "threat_001",
        "type": "environmental",
        "severity": "high",
        "description": "Smoke propagation blocking primary exit routes",
        "affected_floors": [12, 13, 14, 15],
        "timeline": {
          "onset": 120,
          "peak": 300,
          "duration": 600
        }
      },
      {
        "id": "threat_002",
        "type": "infrastructure",
        "severity": "medium",
        "description": "Elevator system shutdown affecting mobility-impaired evacuation",
        "affected_population": 12,
        "alternative_routes": ["stairwell_a", "stairwell_c"]
      }
    ],
    "vulnerabilities": [
      {
        "id": "vuln_001",
        "category": "evacuation_capacity",
        "description": "Insufficient stairwell capacity for building occupancy",
        "current_capacity": 800,
        "required_capacity": 1200,
        "severity": "high"
      },
      {
        "id": "vuln_002",
        "category": "communication",
        "description": "Limited emergency communication systems on upper floors",
        "affected_floors": [16, 17, 18, 19, 20],
        "severity": "medium"
      }
    ],
    "mitigation_strategies": [
      {
        "id": "mitigation_001",
        "type": "infrastructure",
        "priority": "high",
        "description": "Install additional emergency stairwell on east side",
        "estimated_cost": 500000,
        "implementation_time": "6 months",
        "risk_reduction": 0.35
      },
      {
        "id": "mitigation_002",
        "type": "procedural",
        "priority": "medium",
        "description": "Implement phased evacuation protocol for upper floors",
        "estimated_cost": 15000,
        "implementation_time": "2 weeks",
        "risk_reduction": 0.20
      }
    ]
  },
  "safety_metrics": {
    "evacuation_time": 1080,
    "bottlenecks": [
      {
        "location": "stairwell_b_floor_15",
        "severity": "critical",
        "delay_time": 180,
        "affected_agents": 45
      },
      {
        "location": "main_lobby_exit",
        "severity": "medium",
        "delay_time": 60,
        "affected_agents": 120
      }
    ],
    "capacity_utilization": 0.85,
    "accessibility_score": 0.65
  },
  "recommendations": [
    {
      "category": "immediate",
      "priority": "urgent",
      "description": "Conduct emergency evacuation drill focusing on upper floor procedures",
      "implementation_time": "1 week",
      "cost": "low"
    },
    {
      "category": "short_term",
      "priority": "high",
      "description": "Install emergency communication systems on floors 16-20",
      "implementation_time": "1 month",
      "cost": "medium"
    },
    {
      "category": "long_term",
      "priority": "high",
      "description": "Add secondary emergency stairwell to reduce evacuation time",
      "implementation_time": "6 months",
      "cost": "high"
    }
  ]
}

Scenario Types

Emergency Response

Fire evacuations
Natural disaster response
Medical emergencies
Hazmat incidents

Key Metrics: Evacuation time, casualty estimates, response effectiveness

Urban Planning

Traffic flow analysis
Pedestrian movement studies
Public transportation impact
Development impact assessment

Key Metrics: Congestion levels, accessibility, capacity utilization

Security Assessment

Crowd control scenarios
Event security planning
Threat response evaluation
Perimeter security analysis

Key Metrics: Security coverage, response time, vulnerability assessment

Disaster Simulation

Earthquake response
Flood evacuation
Hurricane preparation
Infrastructure failure

Key Metrics: Damage assessment, recovery time, resource allocation

Risk Analysis Features

Real-time Threat Detection

Dynamic threat identification during simulation
Adaptive risk scoring based on evolving conditions
Predictive threat modeling

Multi-layered Analysis

Individual agent risk assessment
Group dynamics risk evaluation
Infrastructure vulnerability analysis
Environmental hazard modeling

Temporal Risk Modeling

Time-based risk evolution
Peak risk period identification
Long-term risk trend analysis

Mitigation Planning

Automated mitigation strategy generation
Cost-benefit analysis of interventions
Implementation timeline recommendations

Integration with Other APIs

Combine with Route Risk Analysis

// First, analyze route risks
const routeRisk = await analyzeRouteRisk(evacuationRoute);

// Then create simulation with risk context
const simulation = await createRiskSimulation({
  prompt: "Emergency evacuation following the analyzed route",
  risk_analysis: {
    enabled: true,
    baseline_risks: routeRisk.threats,
    resolution: "high"
  }
});

Enhance with MARL Real-time Data

// Use MARL WebSocket for real-time risk updates
ws.onmessage = (event) => {
  const message = JSON.parse(event.data);
  
  if (message.type === 'update_flee_status') {
    // Update risk assessment based on agent behavior
    updateRiskAssessment(message.payload);
  }
};

Status Codes

201

Created

Simulation with risk analysis successfully queued

400

Bad Request

Invalid request parameters or risk analysis configuration

401

Unauthorized

Invalid or missing API key

429

Too Many Requests

Rate limit exceeded

500

Internal Server Error

Server error during simulation or risk analysis

Best Practices

Scenario-Specific Configuration: Choose appropriate risk types for your scenario
Resolution vs Performance: Higher resolution provides more detail but takes longer
Temporal Considerations: Include time windows for time-sensitive scenarios
Mitigation Planning: Enable mitigation recommendations for actionable insights
Iterative Refinement: Use results to refine subsequent simulations

Next Steps

Review Route Risk Analysis for complementary risk assessment
Explore Urban Mobility MARL for real-time risk monitoring
Check Simulation Results for accessing complete risk data

Simulation APIs

Urban Mobility MARL

Risk Assessment

Overview

Authentication

Request Body

Example Requests

Response

Example Response

Scenario Types

Emergency Response

Urban Planning

Security Assessment

Disaster Simulation

Risk Analysis Features

Real-time Threat Detection

Multi-layered Analysis

Temporal Risk Modeling

Mitigation Planning

Integration with Other APIs

Combine with Route Risk Analysis

Enhance with MARL Real-time Data

Status Codes

Best Practices

Next Steps

Simulation APIs

Urban Mobility MARL

Risk Assessment

​Overview

​Authentication

​Request Body

​Example Requests

​Response

​Example Response

​Scenario Types

​Emergency Response

​Urban Planning

​Security Assessment

​Disaster Simulation

​Risk Analysis Features

​Real-time Threat Detection

​Multi-layered Analysis

​Temporal Risk Modeling

​Mitigation Planning

​Integration with Other APIs

​Combine with Route Risk Analysis

​Enhance with MARL Real-time Data

​Status Codes

​Best Practices

​Next Steps

Overview

Authentication

Request Body

Example Requests

Response

Example Response

Scenario Types

Emergency Response

Urban Planning

Security Assessment

Disaster Simulation

Risk Analysis Features

Real-time Threat Detection

Multi-layered Analysis

Temporal Risk Modeling

Mitigation Planning

Integration with Other APIs

Combine with Route Risk Analysis

Enhance with MARL Real-time Data

Status Codes

Best Practices

Next Steps