ConflictService

Armed conflict data from ACLED, UCDP, and HAPI/HDX

The ConflictService provides APIs for accessing armed conflict event data from multiple authoritative sources including ACLED (Armed Conflict Location & Event Data Project), UCDP (Uppsala Conflict Data Program), and HAPI/HDX (Humanitarian API) for humanitarian summaries.

Base Path

/api/conflict/v1

ListAcledEvents

Retrieves armed conflict events from the ACLED dataset with filtering by time range and country.

Endpoint: GET /api/conflict/v1/list-acled-events

Request Parameters

start · int64

Start of time range (inclusive), Unix epoch milliseconds

end · int64

End of time range (inclusive), Unix epoch milliseconds

page_size · int32

Maximum items per page (1-100)

cursor · string

Cursor for next page

country · string

Optional country filter (ISO 3166-1 alpha-2)

Response

events · AcledConflictEvent[]

The list of ACLED conflict events

Show AcledConflictEvent

id · string · required

Unique ACLED event identifier

event_type · string

ACLED event type classification (e.g., “Battles”, “Explosions/Remote violence”)

country · string

Country where the event occurred

location · GeoCoordinates

Geographic location of the event

occurred_at · int64

Time the event occurred, as Unix epoch milliseconds

fatalities · int32

Reported fatalities from this event

actors · string[]

Named actors involved in the event

source · string

Source article or report

admin1 · string

Administrative region within the country

pagination · PaginationResponse

Pagination metadata

Example Request

curl "https://your-domain.com/api/conflict/v1/list-acled-events?start=1704067200000&end=1706745600000&country=UA&page_size=50"

Example Response

{
  "events": [
    {
      "id": "12345678",
      "event_type": "Battles",
      "country": "Ukraine",
      "location": {
        "latitude": 48.379433,
        "longitude": 31.16558
      },
      "occurred_at": 1704153600000,
      "fatalities": 12,
      "actors": ["Military Forces of Ukraine", "Military Forces of Russia"],
      "source": "Reuters",
      "admin1": "Dnipropetrovska"
    }
  ],
  "pagination": {
    "cursor": "eyJvZmZzZXQiOjUwfQ==",
    "has_more": true
  }
}

---

ListUcdpEvents

Retrieves georeferenced violence events from the UCDP (Uppsala Conflict Data Program) dataset.

Endpoint: GET /api/conflict/v1/list-ucdp-events

Request Parameters

start · int64

Start of time range (inclusive), Unix epoch milliseconds

end · int64

End of time range (inclusive), Unix epoch milliseconds

page_size · int32

Maximum items per page (1-100)

cursor · string

Cursor for next page

country · string

Optional country filter (ISO 3166-1 alpha-2)

Response

events · UcdpViolenceEvent[]

The list of UCDP violence events

Show UcdpViolenceEvent

id · string · required

Unique UCDP event identifier

date_start · int64

Start date of the event, as Unix epoch milliseconds

date_end · int64

End date of the event, as Unix epoch milliseconds

location · GeoCoordinates

Geographic location of the event

country · string

Country where the event occurred

side_a · string

Primary party in the conflict (Side A)

side_b · string

Secondary party in the conflict (Side B)

deaths_best · int32

Best estimate of deaths

deaths_low · int32

Low estimate of deaths

deaths_high · int32

High estimate of deaths

violence_type · UcdpViolenceType

Type of violence: UCDP_VIOLENCE_TYPE_STATE_BASED, UCDP_VIOLENCE_TYPE_NON_STATE, or UCDP_VIOLENCE_TYPE_ONE_SIDED

source_original · string

Original source of the event report

pagination · PaginationResponse

Pagination metadata

Example Request

curl "https://your-domain.com/api/conflict/v1/list-ucdp-events?start=1704067200000&end=1706745600000&page_size=25"

---

GetHumanitarianSummary

Retrieves a humanitarian overview for a country from HAPI/HDX, including conflict event counts and fatality statistics.

Endpoint: GET /api/conflict/v1/get-humanitarian-summary

Request Parameters

country_code · string · required

ISO 3166-1 alpha-2 country code (e.g., “YE”, “SD”, “SO”)

Response

summary · HumanitarianCountrySummary

The humanitarian summary for the country

Show HumanitarianCountrySummary

country_code · string

ISO 3166-1 alpha-2 country code

country_name · string

Country name

conflict_events_total · int32

Total conflict events in the reference period

conflict_political_violence_events · int32

Political violence + civilian targeting event count

conflict_fatalities · int32

Total fatalities from political violence and civilian targeting

reference_period · string

Reference period start date (YYYY-MM-DD)

conflict_demonstrations · int32

Number of demonstration events

updated_at · int64

Last data update time, as Unix epoch milliseconds

Example Request

curl "https://your-domain.com/api/conflict/v1/get-humanitarian-summary?country_code=YE"

Example Response

{
  "summary": {
    "country_code": "YE",
    "country_name": "Yemen",
    "conflict_events_total": 1247,
    "conflict_political_violence_events": 892,
    "conflict_fatalities": 3421,
    "reference_period": "2024-01-01",
    "conflict_demonstrations": 143,
    "updated_at": 1709251200000
  }
}

---

ListIranEvents

Retrieves scraped conflict events from LiveUAMap Iran for real-time situational awareness.

Endpoint: GET /api/conflict/v1/list-iran-events

Request Parameters

No parameters required.

Response

events · IranEvent[]

The list of Iran conflict events

Show IranEvent

id · string

Unique event identifier

title · string

Event title

category · string

Event category

source_url · string

URL to the source article

latitude · double

Event latitude

longitude · double

Event longitude

location_name · string

Human-readable location name

timestamp · int64

Event timestamp, as Unix epoch milliseconds

severity · string

Event severity level

scraped_at · int64

Timestamp when the data was scraped, as Unix epoch milliseconds

Example Request

curl "https://your-domain.com/api/conflict/v1/list-iran-events"