API Documentation

Access Ukraine War Analytics data programmatically through our REST API. Build applications, conduct research, or integrate conflict data into your projects.

REST APIJSON ResponsesRate Limited

Quick Start

1. Base URL

https://ukraine-war-analytics.online/api/v1

All API requests should be made to this base URL.

2. Authentication

Authorization: Bearer YOUR_API_KEY

Include your API key in the header for all requests.

Quick Example

curl -X GET "https://ukraine-war-analytics.online/api/v1/statistics/summary" \
  -H "Authorization: Bearer YOUR_API_KEY"

Rate Limits & Quotas

Free Tier

•1,000 requests/day
•60 requests/minute
•100 results per request
•Basic endpoints only

Researcher

•50,000 requests/day
•300 requests/minute
•500 results per request
•All endpoints
•Bulk export available

Enterprise

•Unlimited requests
•Dedicated rate limit
•Full data export
•Priority support
•Custom integrations

Academic & Research Access: Researchers and journalists can apply for free elevated access. Contact us with your credentials and use case.

API Endpoints

GET/api/v1/events

Retrieve a paginated list of conflict events. Supports filtering by date range, region, event type, and other criteria.

Parameters

Name	Type	Required	Description
start_date	string (YYYY-MM-DD)	No	Filter events from this date onwards
end_date	string (YYYY-MM-DD)	No	Filter events up to this date
region	string	No	Filter by oblast/region name (e.g., "Kharkiv Oblast")
event_type	string	No	Filter by event type (battles, shelling, explosions, etc.)
page	integer	No	Page number for pagination (default: 1)
limit	integer	No	Results per page (default: 50, max: 500)
sort	string	No	Sort order: "date_asc" or "date_desc" (default)

Response Fields

totalinteger— Total number of events matching criteria

pageinteger— Current page number

pagesinteger— Total number of pages

eventsarray— Array of event objects

Example Response

{
  "total": 123747,
  "page": 1,
  "pages": 2475,
  "events": [
    {
      "id": "UKR2024-01-15-0001",
      "date": "2024-01-15",
      "event_type": "Shelling/artillery/missile attack",
      "sub_event_type": "Shelling",
      "location": {
        "name": "Kharkiv",
        "oblast": "Kharkiv Oblast",
        "latitude": 49.9935,
        "longitude": 36.2304
      },
      "actors": {
        "actor1": "Military Forces of Russia",
        "actor2": "Civilians (Ukraine)"
      },
      "fatalities": 2,
      "notes": "Russian missile strike hit residential area...",
      "source": "ACLED"
    }
  ]
}

GET/api/v1/events/{id}

Retrieve detailed information about a specific event by its unique identifier.

Parameters

Name	Type	Required	Description
id	string	Yes	Unique event identifier (e.g., "UKR2024-01-15-0001")

Response Fields

idstring— Unique event identifier

datestring— Event date (YYYY-MM-DD)

event_typestring— Primary event classification

sub_event_typestring— Detailed event classification

locationobject— Geographic information

actorsobject— Parties involved

fatalitiesinteger— Documented fatalities

notesstring— Detailed event description

sourcestring— Data source attribution

related_eventsarray— IDs of related events

GET/api/v1/statistics/summary

Get overall conflict statistics including total events, fatalities, date range coverage, and high-level metrics.

Response Fields

total_eventsinteger— Total documented events

total_fatalitiesinteger— Total documented fatalities

total_daysinteger— Days of conflict covered

date_rangeobject— Start and end dates of data

events_by_typeobject— Event counts by category

last_updatedstring— Data last update timestamp

Example Response

{
  "total_events": 123747,
  "total_fatalities": 28450,
  "total_days": 1442,
  "date_range": {
    "start": "2022-02-24",
    "end": "2026-02-04"
  },
  "events_by_type": {
    "Battles": 42156,
    "Shelling/artillery/missile attack": 38924,
    "Explosions/Remote violence": 21547,
    "Violence against civilians": 15234,
    "Strategic developments": 5886
  },
  "last_updated": "2026-02-04T06:00:00Z"
}

GET/api/v1/statistics/timeline

Get time-series data for events and fatalities. Supports daily, weekly, and monthly granularity.

Parameters

Name	Type	Required	Description
granularity	string	No	"day", "week", or "month" (default: "day")
start_date	string	No	Start date for the timeline
end_date	string	No	End date for the timeline
region	string	No	Filter by region
event_type	string	No	Filter by event type

Response Fields

granularitystring— Time granularity used

dataarray— Array of time period objects with events and fatalities

GET/api/v1/regions

List all Ukrainian regions (oblasts) with summary statistics.

Response Fields

regionsarray— Array of region objects

Example Response

{
  "regions": [
    {
      "id": "kharkiv-oblast",
      "name": "Kharkiv Oblast",
      "name_ua": "Харківська область",
      "capital": "Kharkiv",
      "total_events": 18547,
      "total_fatalities": 4231,
      "area_km2": 31415,
      "population_2021": 2658461,
      "coordinates": {
        "latitude": 49.9935,
        "longitude": 36.2304
      }
    }
  ]
}

GET/api/v1/regions/{region_id}

Get detailed information about a specific region including monthly statistics and top affected locations.

Parameters

Name	Type	Required	Description
region_id	string	Yes	Region identifier (e.g., "kharkiv-oblast")

Response Fields

regionobject— Region details

monthly_statsarray— Monthly event/fatality counts

top_locationsarray— Most affected locations in region

event_typesobject— Breakdown by event type

GET/api/v1/equipment

Get documented military equipment losses for both Russia and Ukraine.

Parameters

Name	Type	Required	Description
country	string	No	"russia" or "ukraine" (default: both)
category	string	No	Equipment category (tanks, ifvs, aircraft, etc.)
status	string	No	Loss status (destroyed, damaged, captured, abandoned)

Response Fields

russiaobject— Russian equipment losses by category

ukraineobject— Ukrainian equipment losses by category

last_updatedstring— Data last update timestamp

Example Response

{
  "russia": {
    "tanks": {
      "total": 3247,
      "destroyed": 2156,
      "damaged": 234,
      "captured": 567,
      "abandoned": 290
    },
    "ifvs": {
      "total": 6521,
      "destroyed": 4123,
      "damaged": 567,
      "captured": 1231,
      "abandoned": 600
    }
  },
  "ukraine": {
    "tanks": {
      "total": 892,
      "destroyed": 612,
      "damaged": 89,
      "captured": 145,
      "abandoned": 46
    }
  },
  "last_updated": "2026-02-04T06:00:00Z"
}

GET/api/v1/equipment/{category}

Get detailed equipment losses for a specific category with model-level breakdown.

Parameters

Name	Type	Required	Description
category	string	Yes	Equipment category (tanks, ifvs, artillery, etc.)
country	string	No	Filter by country

Response Fields

categorystring— Equipment category

modelsarray— Losses by specific model

timelinearray— Monthly loss progression

GET/api/v1/locations

List all tracked locations with event counts and geographic coordinates.

Parameters

Name	Type	Required	Description
region	string	No	Filter by oblast
min_events	integer	No	Minimum event count
sort	string	No	"events" or "name" (default: "events")

Response Fields

totalinteger— Total locations

locationsarray— Array of location objects

GET/api/v1/locations/{location_id}

Get detailed information about a specific location including all recorded events.

Parameters

Name	Type	Required	Description
location_id	string	Yes	Location identifier

Response Fields

locationobject— Location details

eventsarray— All events at this location

statisticsobject— Location statistics

GET/api/v1/refugees

Get Ukrainian refugee statistics by host country and time series data.

Parameters

Name	Type	Required	Description
country	string	No	Filter by host country

Response Fields

total_refugeesinteger— Total refugees abroad

total_idpinteger— Internally displaced persons

by_countryarray— Refugees by host country

timelinearray— Monthly refugee numbers

Code Examples

Python

JavaScript

cURL

🐍 Python

import requests

# Base URL for the API
BASE_URL = "https://ukraine-war-analytics.online/api/v1"

# Your API key (required for authenticated requests)
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}

# Example 1: Get recent events
def get_recent_events(days=7, region=None):
    """Fetch events from the last N days"""
    from datetime import datetime, timedelta
    
    end_date = datetime.now().strftime("%Y-%m-%d")
    start_date = (datetime.now() - timedelta(days=days)).strftime("%Y-%m-%d")
    
    params = {
        "start_date": start_date,
        "end_date": end_date,
        "limit": 100
    }
    
    if region:
        params["region"] = region
    
    response = requests.get(
        f"{BASE_URL}/events",
        headers=headers,
        params=params
    )
    
    return response.json()

# Example 2: Get statistics summary
def get_summary():
    """Fetch overall conflict statistics"""
    response = requests.get(
        f"{BASE_URL}/statistics/summary",
        headers=headers
    )
    return response.json()

# Example 3: Get equipment losses
def get_equipment_losses(category=None, country=None):
    """Fetch equipment loss data"""
    params = {}
    if category:
        params["category"] = category
    if country:
        params["country"] = country
    
    response = requests.get(
        f"{BASE_URL}/equipment",
        headers=headers,
        params=params
    )
    return response.json()

# Example 4: Build a timeline chart
def get_timeline_data(granularity="week", months=6):
    """Get time series data for visualization"""
    from datetime import datetime, timedelta
    
    end_date = datetime.now()
    start_date = end_date - timedelta(days=30*months)
    
    params = {
        "granularity": granularity,
        "start_date": start_date.strftime("%Y-%m-%d"),
        "end_date": end_date.strftime("%Y-%m-%d")
    }
    
    response = requests.get(
        f"{BASE_URL}/statistics/timeline",
        headers=headers,
        params=params
    )
    
    return response.json()

# Usage examples
if __name__ == "__main__":
    # Get events from Kharkiv in the last week
    kharkiv_events = get_recent_events(days=7, region="Kharkiv Oblast")
    print(f"Events in Kharkiv (last 7 days): {len(kharkiv_events['events'])}")
    
    # Get summary statistics
    summary = get_summary()
    print(f"Total events documented: {summary['total_events']:,}")
    print(f"Days of conflict: {summary['total_days']}")
    
    # Get Russian tank losses
    tanks = get_equipment_losses(category="tanks", country="russia")
    print(f"Russian tanks lost: {tanks['russia']['tanks']['total']:,}")

📜 JavaScript / Node.js

// Using fetch API (Browser/Node.js 18+)
const BASE_URL = "https://ukraine-war-analytics.online/api/v1";
const API_KEY = "YOUR_API_KEY";

const headers = {
  "Authorization": `Bearer ${API_KEY}`,
  "Content-Type": "application/json"
};

// Example 1: Get recent events
async function getRecentEvents(days = 7, region = null) {
  const endDate = new Date().toISOString().split('T')[0];
  const startDate = new Date(Date.now() - days * 24 * 60 * 60 * 1000)
    .toISOString().split('T')[0];
  
  const params = new URLSearchParams({
    start_date: startDate,
    end_date: endDate,
    limit: 100
  });
  
  if (region) {
    params.append('region', region);
  }
  
  const response = await fetch(
    `${BASE_URL}/events?${params}`,
    { headers }
  );
  
  return response.json();
}

// Example 2: Get statistics summary
async function getSummary() {
  const response = await fetch(
    `${BASE_URL}/statistics/summary`,
    { headers }
  );
  return response.json();
}

// Example 3: Get equipment losses
async function getEquipmentLosses(category = null, country = null) {
  const params = new URLSearchParams();
  if (category) params.append('category', category);
  if (country) params.append('country', country);
  
  const url = params.toString() 
    ? `${BASE_URL}/equipment?${params}` 
    : `${BASE_URL}/equipment`;
  
  const response = await fetch(url, { headers });
  return response.json();
}

// Example 4: React hook for events
function useConflictEvents(region, days = 7) {
  const [events, setEvents] = React.useState([]);
  const [loading, setLoading] = React.useState(true);
  const [error, setError] = React.useState(null);
  
  React.useEffect(() => {
    setLoading(true);
    getRecentEvents(days, region)
      .then(data => {
        setEvents(data.events);
        setLoading(false);
      })
      .catch(err => {
        setError(err);
        setLoading(false);
      });
  }, [region, days]);
  
  return { events, loading, error };
}

// Usage examples
async function main() {
  // Get events from Donetsk
  const donetskEvents = await getRecentEvents(7, "Donetsk Oblast");
  console.log(`Events in Donetsk: ${donetskEvents.events.length}`);
  
  // Get summary
  const summary = await getSummary();
  console.log(`Total events: ${summary.total_events.toLocaleString()}`);
  
  // Get equipment losses
  const equipment = await getEquipmentLosses();
  console.log(`Russian tanks lost: ${equipment.russia.tanks.total}`);
}

main().catch(console.error);

💻 cURL

# Get recent events
curl -X GET "https://ukraine-war-analytics.online/api/v1/events?start_date=2024-01-01&end_date=2024-01-31&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

# Get events for specific region
curl -X GET "https://ukraine-war-analytics.online/api/v1/events?region=Kharkiv%20Oblast&limit=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Get summary statistics
curl -X GET "https://ukraine-war-analytics.online/api/v1/statistics/summary" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Get timeline data (weekly granularity)
curl -X GET "https://ukraine-war-analytics.online/api/v1/statistics/timeline?granularity=week&start_date=2023-01-01" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Get all regions
curl -X GET "https://ukraine-war-analytics.online/api/v1/regions" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Get equipment losses (Russian tanks)
curl -X GET "https://ukraine-war-analytics.online/api/v1/equipment?country=russia&category=tanks" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Get specific event details
curl -X GET "https://ukraine-war-analytics.online/api/v1/events/UKR2024-01-15-0001" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Get locations in region
curl -X GET "https://ukraine-war-analytics.online/api/v1/locations?region=Donetsk%20Oblast&min_events=100" \
  -H "Authorization: Bearer YOUR_API_KEY"

Error Codes

Code	Status	Description
200	OK	Request successful
400	Bad Request	Invalid parameters or malformed request
401	Unauthorized	Missing or invalid API key
403	Forbidden	Access denied to this resource
404	Not Found	Requested resource does not exist
429	Too Many Requests	Rate limit exceeded. Retry after cooldown.
500	Server Error	Internal server error. Please retry or contact support.

Error Response Format

{
  "error": {
    "code": 400,
    "message": "Invalid date format. Use YYYY-MM-DD.",
    "field": "start_date"
  }
}

Data Formats & Types

Date Formats

DateYYYY-MM-DD
TimestampISO 8601
Example2024-01-15T14:30:00Z

Event Types

Battles — Armed clashes
Shelling/artillery/missile attack
Explosions/Remote violence
Violence against civilians
Strategic developments

Loss Status

destroyed — Completely destroyed
damaged — Damaged but potentially repairable
captured — Captured by opposing force
abandoned — Left behind/discarded

JSON Schema

Formal JSON Schema definitions for validating API responses and generating client code. Compatible with JSON Schema Draft-07.

Event Object Schema

{
  "$schema": "https://json-schema.org/draft-07/schema#",
  "$id": "https://ukraine-war-analytics.online/schemas/event.json",
  "title": "ConflictEvent",
  "type": "object",
  "required": ["event_id", "date", "event_type", "location", "fatalities"],
  "properties": {
    "event_id":     { "type": "string",  "description": "Unique event identifier (ACLED-based)" },
    "date":         { "type": "string",  "format": "date", "description": "ISO 8601 date of event" },
    "event_type":   { "type": "string",  "enum": ["Battles", "Explosions/Remote violence", "Violence against civilians", "Protests", "Strategic developments"] },
    "sub_event_type": { "type": "string", "description": "Sub-category of the event type" },
    "location": {
      "type": "object",
      "required": ["name", "lat", "lng", "admin1"],
      "properties": {
        "name":   { "type": "string",  "description": "Location name" },
        "lat":    { "type": "number",  "minimum": -90,  "maximum": 90  },
        "lng":    { "type": "number",  "minimum": -180, "maximum": 180 },
        "admin1": { "type": "string",  "description": "Oblast / region name" }
      }
    },
    "actors": {
      "type": "object",
      "properties": {
        "actor1": { "type": "string", "description": "Primary actor name" },
        "actor2": { "type": "string", "description": "Secondary actor name" }
      }
    },
    "fatalities": { "type": "integer", "minimum": 0, "description": "Estimated fatalities" },
    "notes":      { "type": "string",  "description": "Narrative description of the event" },
    "source":     { "type": "string",  "description": "Original data source (e.g. ACLED)" }
  }
}

Equipment Loss Object Schema

{
  "$schema": "https://json-schema.org/draft-07/schema#",
  "$id": "https://ukraine-war-analytics.online/schemas/equipment-loss.json",
  "title": "EquipmentLoss",
  "type": "object",
  "required": ["id", "system", "category", "side", "status", "date_confirmed"],
  "properties": {
    "id":             { "type": "string",  "description": "Unique loss record identifier" },
    "system":         { "type": "string",  "description": "Equipment system name (e.g. T-72B3)" },
    "category":       { "type": "string",  "enum": ["tanks", "armoured_vehicles", "artillery", "mlrs", "air_defence", "aircraft", "helicopters", "naval", "drones", "vehicles", "other"] },
    "side":           { "type": "string",  "enum": ["Russia", "Ukraine"] },
    "status":         { "type": "string",  "enum": ["destroyed", "damaged", "captured", "abandoned"] },
    "date_confirmed": { "type": "string",  "format": "date", "description": "Date loss was visually confirmed" },
    "evidence_url":   { "type": "string",  "format": "uri",  "description": "Link to photographic/video evidence" },
    "location": {
      "type": "object",
      "properties": {
        "name":   { "type": "string" },
        "lat":    { "type": "number" },
        "lng":    { "type": "number" },
        "oblast": { "type": "string" }
      }
    },
    "quantity": { "type": "integer", "minimum": 1, "default": 1 }
  }
}

Schema Usage

Use these schemas with AJV, Zod, or any JSON Schema validator to validate API responses at runtime.

/schemas/event.json /schemas/equipment-loss.json

Webhooks (Beta)

Subscribe to real-time updates when new events are recorded. Webhooks are available for Researcher and Enterprise tier users.

Available Events

event.created — New event recorded
equipment.updated — Equipment loss updated
statistics.daily — Daily summary

Webhook Payload

{
  "type": "event.created",
  "timestamp": "2024-01-15T14:30:00Z",
  "data": { ... }
}

SDKs & Libraries

🐍

Python SDK

pip install ukraine-war-analyticsDocumentation →

📦

JavaScript SDK

npm install ukraine-war-analyticsDocumentation →

🔷

R Package

Coming SoonIn development

Terms of Use & Attribution

Required Attribution

When using data from our API, please include attribution:

Data source: Ukraine War Analytics (ukraine-war-analytics.online)

Permitted Uses

✓ Academic research and publications
✓ Journalism and news reporting
✓ Non-commercial applications
✓ Data analysis and visualization

By using our API, you agree to our Terms of Service and Privacy Policy. Commercial use requires a separate license agreement.

📧 Contact Support

Questions about the API? Need help with integration? Reach out to our team.

❓ FAQ

Find answers to common questions about our data and platform.

API Documentation

Quick Start

1. Base URL

2. Authentication

Quick Example

Rate Limits & Quotas

Free Tier

Researcher

Enterprise

API Endpoints

Parameters

Response Fields

Example Response

Parameters

Response Fields

Response Fields

Example Response

Parameters

Response Fields

Response Fields

Example Response

Parameters

Response Fields

Parameters

Response Fields

Example Response

Parameters

Response Fields

Parameters

Response Fields

Parameters

Response Fields

Parameters

Response Fields

Code Examples

🐍 Python

📜 JavaScript / Node.js

💻 cURL

Error Codes

Error Response Format

Data Formats & Types

Date Formats

Event Types

Equipment Categories

Loss Status

JSON Schema

Event Object Schema

Equipment Loss Object Schema

Schema Usage

Webhooks (Beta)

Available Events

Webhook Payload

SDKs & Libraries

Python SDK

JavaScript SDK

R Package

Terms of Use & Attribution

Required Attribution

Permitted Uses

📧 Contact Support

❓ FAQ