Radius Risk Analysis - World Lens API Documentation

Overview

The Radius Risk Analysis API evaluates potential threats and hazards within a circular area around a specified geographic point. This endpoint is ideal for assessing risks in a specific location, planning safe zones, or analyzing area-wide security concerns.

Authentication

curl -X GET "https://api.worldlens.co/risk-assessment/radius/?latitude=37.7749&longitude=-122.4194&radius_km=5" \
  -H "Authorization: Api-Key YOUR_API_KEY"

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

Query Parameters

latitude

number

required

Center latitude coordinate (-90 to 90)

longitude

number

required

Center longitude coordinate (-180 to 180)

radius_km

number

required

Radius in kilometers (0.1 to 100)

num_points

integer

default:"100"

Number of analysis points to generate within the radius (10 to 1000)

Anonymous users: max 100 points
Authenticated users: max 1000 points

risk_types

string

Comma-separated list of risk types to analyze. If not provided, all types are assessed.Available types: geopolitical, environmental, infrastructure, crime, traffic, weather

resolution

string

default:"medium"

Analysis resolution: low, medium, high

time

string

ISO 8601 timestamp for time-specific analysis. Defaults to current time.

Example Requests

curl -X GET "https://api.worldlens.co/risk-assessment/radius/?latitude=37.7749&longitude=-122.4194&radius_km=2" \
  -H "Authorization: Api-Key YOUR_API_KEY"

Response

riskPoints

array

Array of risk assessment points within the specified radius

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[].distance

number

Distance from center point in kilometers

riskPoints[].threats

array

Array of specific threats identified at this location

center

object

Center point information

Show center properties

center.latitude

number

Center latitude coordinate

center.longitude

number

Center longitude coordinate

center.radius_km

number

Analysis radius in kilometers

summary

object

Area risk summary statistics

Show summary properties

summary.overallRisk

string

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

summary.maxRiskWeight

number

Highest risk weight found in the area

summary.averageRisk

number

Average risk weight across all points

summary.area_km2

number

Total analyzed area in square kilometers

summary.highRiskZones

integer

Number of high-risk zones identified

summary.safeZones

integer

Number of low-risk zones identified

threats

array

Detailed threat information for the area

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[].affected_radius

number

Radius of threat influence in kilometers

threats[].confidence

number

Confidence score for the threat assessment (0.0 to 1.0)

zones

array

Risk zone classifications within the area

Show zones structure

zones[].id

string

Unique zone identifier

zones[].type

string

Zone type: safe, caution, danger, critical

zones[].boundary

array

Array of coordinates defining the zone boundary

zones[].riskLevel

string

Zone risk level

zones[].primaryThreats

array

Main threats affecting this zone

Example Response

{
  "riskPoints": [
    {
      "lat": 37.7749,
      "lng": -122.4194,
      "weight": 0.3,
      "riskLevel": "medium",
      "distance": 0.0,
      "threats": ["moderate_traffic", "minor_crime_activity"]
    },
    {
      "lat": 37.7759,
      "lng": -122.4184,
      "weight": 0.8,
      "riskLevel": "high",
      "distance": 1.2,
      "threats": ["active_construction", "high_crime_area"]
    },
    {
      "lat": 37.7739,
      "lng": -122.4204,
      "weight": 0.1,
      "riskLevel": "low",
      "distance": 1.1,
      "threats": []
    }
  ],
  "center": {
    "latitude": 37.7749,
    "longitude": -122.4194,
    "radius_km": 2.0
  },
  "summary": {
    "overallRisk": "medium",
    "maxRiskWeight": 0.8,
    "averageRisk": 0.4,
    "area_km2": 12.57,
    "highRiskZones": 2,
    "safeZones": 5
  },
  "threats": [
    {
      "id": "threat_001",
      "type": "infrastructure",
      "severity": "high",
      "description": "Major construction project causing significant disruption",
      "location": {
        "lat": 37.7759,
        "lng": -122.4184
      },
      "affected_radius": 0.5,
      "confidence": 0.92
    },
    {
      "id": "threat_002",
      "type": "crime",
      "severity": "medium",
      "description": "Elevated crime activity in commercial district",
      "location": {
        "lat": 37.7755,
        "lng": -122.4180
      },
      "affected_radius": 0.3,
      "confidence": 0.78
    }
  ],
  "zones": [
    {
      "id": "zone_001",
      "type": "safe",
      "boundary": [
        [37.7740, -122.4210],
        [37.7740, -122.4200],
        [37.7750, -122.4200],
        [37.7750, -122.4210]
      ],
      "riskLevel": "low",
      "primaryThreats": []
    },
    {
      "id": "zone_002",
      "type": "danger",
      "boundary": [
        [37.7755, -122.4190],
        [37.7755, -122.4180],
        [37.7765, -122.4180],
        [37.7765, -122.4190]
      ],
      "riskLevel": "high",
      "primaryThreats": ["construction", "crime"]
    }
  ]
}

Use Cases

Emergency Planning

# Assess risks around a hospital for emergency evacuation planning
curl -X GET "https://api.worldlens.co/risk-assessment/radius/?latitude=37.7749&longitude=-122.4194&radius_km=3&risk_types=environmental,infrastructure&num_points=300" \
  -H "Authorization: Api-Key YOUR_API_KEY"

Event Security

# Analyze security risks around an event venue
curl -X GET "https://api.worldlens.co/risk-assessment/radius/?latitude=37.7749&longitude=-122.4194&radius_km=1&risk_types=crime,geopolitical&time=2024-01-15T19:00:00Z" \
  -H "Authorization: Api-Key YOUR_API_KEY"

Real Estate Assessment

# Evaluate neighborhood safety for property investment
curl -X GET "https://api.worldlens.co/risk-assessment/radius/?latitude=37.7749&longitude=-122.4194&radius_km=0.5&risk_types=crime,environmental&resolution=high" \
  -H "Authorization: Api-Key YOUR_API_KEY"

Logistics Planning

# Assess risks around a distribution center
curl -X GET "https://api.worldlens.co/risk-assessment/radius/?latitude=37.7749&longitude=-122.4194&radius_km=10&risk_types=traffic,infrastructure,weather" \
  -H "Authorization: Api-Key YOUR_API_KEY"

Status Codes

200

Risk analysis completed successfully

400

Bad Request

Invalid coordinates, radius, or other 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 Responses

{
  "error": "Invalid radius: radius_km must be between 0.1 and 100",
  "code": "INVALID_RADIUS",
  "details": {
    "field": "radius_km",
    "min_value": 0.1,
    "max_value": 100,
    "provided_value": 150
  }
}

{
  "error": "Too many points requested for anonymous user",
  "code": "POINTS_LIMIT_EXCEEDED",
  "details": {
    "max_points_anonymous": 100,
    "max_points_authenticated": 1000,
    "requested_points": 500
  }
}

Integration Examples

JavaScript/Web

async function analyzeAreaRisk(lat, lng, radius) {
    const params = new URLSearchParams({
        latitude: lat,
        longitude: lng,
        radius_km: radius,
        num_points: 200,
        resolution: 'high'
    });
    
    const response = await fetch(`https://api.worldlens.co/risk-assessment/radius/?${params}`, {
        headers: {
            'Authorization': 'Api-Key YOUR_API_KEY'
        }
    });
    
    const riskData = await response.json();
    
    // Create heat map visualization
    createRiskHeatMap(riskData.riskPoints);
    
    // Highlight high-risk zones
    riskData.zones.forEach(zone => {
        if (zone.riskLevel === 'high') {
            highlightDangerZone(zone.boundary);
        }
    });
}

Python

import requests

def analyze_area_risk(lat, lng, radius_km, api_key, num_points=100):
    url = "https://api.worldlens.co/risk-assessment/radius/"
    params = {
        "latitude": lat,
        "longitude": lng,
        "radius_km": radius_km,
        "num_points": num_points,
        "resolution": "high"
    }
    headers = {
        "Authorization": f"Api-Key {api_key}"
    }
    
    response = requests.get(url, params=params, headers=headers)
    return response.json()

# Example usage
risk_data = analyze_area_risk(37.7749, -122.4194, 2.0, "your_api_key", 300)

# Find high-risk areas
high_risk_points = [
    point for point in risk_data['riskPoints'] 
    if point['weight'] > 0.7
]

R

library(httr)
library(jsonlite)

analyze_area_risk <- function(lat, lng, radius_km, api_key) {
  url <- "https://api.worldlens.co/risk-assessment/radius/"
  
  response <- GET(
    url,
    query = list(
      latitude = lat,
      longitude = lng,
      radius_km = radius_km,
      num_points = 200
    ),
    add_headers(Authorization = paste("Api-Key", api_key))
  )
  
  content(response, "parsed")
}

# Example usage
risk_data <- analyze_area_risk(37.7749, -122.4194, 2.0, "your_api_key")

Visualization Tips

Heat Maps

Use the weight values to create color-coded heat maps showing risk intensity across the area.

Zone Boundaries

Render the zones boundaries to clearly delineate safe and dangerous areas.

Threat Markers

Place markers at threat locations with icons representing the threat type and severity.

Distance Rings

Show concentric circles at different distances from the center point for spatial reference.

Next Steps

Combine with Route Risk Analysis for comprehensive travel planning
Integrate with Urban Mobility MARL for dynamic risk modeling
Use with Simulation APIs for scenario-based risk assessment

Simulation APIs

Urban Mobility MARL

Risk Assessment

​Overview

​Authentication

​Query Parameters

​Example Requests

​Response

​Example Response

​Use Cases

​Emergency Planning

​Event Security

​Real Estate Assessment

​Logistics Planning

​Status Codes

​Error Responses

​Integration Examples

​JavaScript/Web

​Python

​R

​Visualization Tips

​Heat Maps

​Zone Boundaries

​Threat Markers

​Distance Rings

​Next Steps

Overview

Authentication

Query Parameters

Example Requests

Response

Example Response

Use Cases

Emergency Planning

Event Security

Real Estate Assessment

Logistics Planning

Status Codes

Error Responses

Integration Examples

JavaScript/Web

Python

R

Visualization Tips

Heat Maps

Zone Boundaries

Threat Markers

Distance Rings

Next Steps