GET/api/v1/incidents

Retrieve security incidents with optional filtering

Parameters

statestring

Filter by Nigerian state name

typestring

Filter by incident type (KIDNAPPING, BANDITRY, etc.)

daysnumber

Number of days to look back (default: 30)

limitnumber

Maximum results to return (default: 50, max: 500)

roadstring

Filter by road/highway name

Response Example

{
  "success": true,
  "data": {
    "incidents": [
      {
        "id": "clx...",
        "type": "KIDNAPPING",
        "state": "Kaduna",
        "location": "Abuja-Kaduna Expressway",
        "latitude": 10.5265,
        "longitude": 7.4384,
        "date": "2026-02-28T14:30:00Z",
        "title": "Travellers kidnapped on highway",
        "killed": 0,
        "kidnapped": 8,
        "rescued": 0,
        "injured": 2
      }
    ],
    "count": 1
  },
  "meta": {
    "requestId": "abc123",
    "timestamp": "2026-03-01T12:00:00Z",
    "credits_remaining": 95
  }
}

Code Examples

cURL

curl -X GET "https://safejourney.ai/api/v1/incidents?state=Kaduna&days=7" \
  -H "X-API-Key: sj_live_12345abcdef67890"

Python

import requests

headers = {"X-API-Key": "sj_live_12345abcdef67890"}
params = {"state": "Kaduna", "days": 7}

response = requests.get(
    "https://safejourney.ai/api/v1/incidents",
    headers=headers,
    params=params
)
data = response.json()
print(data)

JavaScript

const response = await fetch(
  'https://safejourney.ai/api/v1/incidents?state=Kaduna&days=7',
  {
    headers: {
      'X-API-Key': 'sj_live_12345abcdef67890'
    }
  }
);
const data = await response.json();
console.log(data);

GET/api/v1/state-risk

Get security risk scores for Nigerian states

Parameters

statestring

Specific state name (returns all states if omitted)

Response Example

{
  "success": true,
  "data": {
    "states": [
      {
        "state": "Kaduna",
        "risk_score": 7.8,
        "incident_count": 42,
        "killed": 23,
        "kidnapped": 67,
        "injured": 15,
        "trend": "up"
      }
    ],
    "period_days": 30
  },
  "meta": {
    "requestId": "def456",
    "timestamp": "2026-03-01T12:00:00Z",
    "credits_remaining": 94
  }
}

Code Examples

cURL

curl -X GET "https://safejourney.ai/api/v1/state-risk?state=Kaduna" \
  -H "X-API-Key: sj_live_12345abcdef67890"

Python

import requests

headers = {"X-API-Key": "sj_live_12345abcdef67890"}

response = requests.get(
    "https://safejourney.ai/api/v1/state-risk",
    headers=headers,
    params={"state": "Kaduna"}
)
data = response.json()
print(f"Risk Score: {data['data']['states'][0]['risk_score']}")

JavaScript

const response = await fetch(
  'https://safejourney.ai/api/v1/state-risk?state=Kaduna',
  {
    headers: {
      'X-API-Key': 'sj_live_your_api_key_here'
    }
  }
);
const data = await response.json();
console.log('Risk Score:', data.data.states[0].risk_score);

GET/api/v1/route-risk

Calculate risk score for a specific route

Parameters

from_statestring

Origin state name

to_statestring

Destination state name

from_latnumber

Origin latitude

from_lngnumber

Origin longitude

to_latnumber

Destination latitude

to_lngnumber

Destination longitude

Response Example

{
  "success": true,
  "data": {
    "risk_score": 6.5,
    "incident_count": 18,
    "casualties": {
      "killed": 12,
      "kidnapped": 34,
      "injured": 8
    },
    "recent_incidents": [],
    "road_segments_affected": 3,
    "safest_time_of_day": "Morning (6AM-12PM)",
    "analysis_period_days": 90
  }
}

Code Examples

cURL

curl -X GET "https://safejourney.ai/api/v1/route-risk?from_state=Lagos&to_state=Abuja" \
  -H "X-API-Key: sj_live_12345abcdef67890"

GET/api/v1/roads

List monitored roads with incident counts and risk levels

Response Example

{
  "success": true,
  "data": {
    "roads": [
      {
        "road": "Abuja-Kaduna Expressway",
        "states": [
          "Kaduna",
          "FCT"
        ],
        "incident_count": 28,
        "casualties": {
          "killed": 15,
          "kidnapped": 42,
          "injured": 10
        },
        "risk_level": "HIGH",
        "risk_score": 8.2
      }
    ],
    "total_monitored": 45,
    "period_days": 90
  }
}

Code Examples

cURL

curl -X GET "https://safejourney.ai/api/v1/roads" \
  -H "X-API-Key: sj_live_12345abcdef67890"

POST/api/v1/alerts/subscribe

Subscribe to real-time security alerts

Parameters

webhook_urlstring

Webhook URL for alerts (either this or telegram_chat_id)

telegram_chat_idstring

Telegram chat ID for alerts

statesarray

Array of state names to monitor

roadsarray

Array of road names to monitor

min_severitystring

Minimum severity: LOW, MEDIUM, HIGH, CRITICAL

Response Example

{
  "success": true,
  "data": {
    "subscription_id": "sub_abc123",
    "states": [
      "Kaduna",
      "Kano"
    ],
    "roads": [
      "Abuja-Kaduna Expressway"
    ],
    "min_severity": "HIGH",
    "webhook_url": "https://example.com/webhook",
    "active": true
  }
}

Code Examples

cURL

curl -X POST "https://safejourney.ai/api/v1/alerts/subscribe" \
  -H "X-API-Key: sj_live_12345abcdef67890" \
  -H "Content-Type: application/json" \
  -d '{
    "webhook_url": "https://example.com/webhook",
    "states": ["Kaduna", "Kano"],
    "min_severity": "HIGH"
  }'

Python

import requests

headers = {
    "X-API-Key": "sj_live_12345abcdef67890",
    "Content-Type": "application/json"
}

payload = {
    "webhook_url": "https://example.com/webhook",
    "states": ["Kaduna", "Kano"],
    "min_severity": "HIGH"
}

response = requests.post(
    "https://safejourney.ai/api/v1/alerts/subscribe",
    headers=headers,
    json=payload
)
data = response.json()
print(f"Subscription ID: {data['data']['subscription_id']}")

SafeJourney.ai

SafeJourney API Documentation

Authentication

Parameters

Response Example

Code Examples

Parameters

Response Example

Code Examples

Parameters

Response Example

Code Examples

Response Example

Code Examples

Rate Limits

Ready to build?