openapi: 3.1.0 info: title: ConflictService API version: 1.0.0 paths: /api/conflict/v1/list-acled-events: get: tags: - ConflictService summary: ListAcledEvents description: ListAcledEvents retrieves armed conflict events from the ACLED dataset. operationId: ListAcledEvents parameters: - name: start in: query description: Start of time range (inclusive), Unix epoch milliseconds. required: false schema: type: string format: int64 - name: end in: query description: End of time range (inclusive), Unix epoch milliseconds. required: false schema: type: string format: int64 - name: page_size in: query description: Maximum items per page (1-100). required: false schema: type: integer format: int32 - name: cursor in: query description: Cursor for next page. required: false schema: type: string - name: country in: query description: Optional country filter (ISO 3166-1 alpha-2). required: false schema: type: string responses: "200": description: Successful response content: application/json: schema: $ref: '#/components/schemas/ListAcledEventsResponse' "400": description: Validation error content: application/json: schema: $ref: '#/components/schemas/ValidationError' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/Error' /api/conflict/v1/list-ucdp-events: get: tags: - ConflictService summary: ListUcdpEvents description: ListUcdpEvents retrieves georeferenced violence events from the UCDP dataset. operationId: ListUcdpEvents parameters: - name: start in: query description: Start of time range (inclusive), Unix epoch milliseconds. required: false schema: type: string format: int64 - name: end in: query description: End of time range (inclusive), Unix epoch milliseconds. required: false schema: type: string format: int64 - name: page_size in: query description: Maximum items per page (1-100). required: false schema: type: integer format: int32 - name: cursor in: query description: Cursor for next page. required: false schema: type: string - name: country in: query description: Optional country filter (ISO 3166-1 alpha-2). required: false schema: type: string responses: "200": description: Successful response content: application/json: schema: $ref: '#/components/schemas/ListUcdpEventsResponse' "400": description: Validation error content: application/json: schema: $ref: '#/components/schemas/ValidationError' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/Error' /api/conflict/v1/get-humanitarian-summary: get: tags: - ConflictService summary: GetHumanitarianSummary description: GetHumanitarianSummary retrieves a humanitarian overview for a country from HAPI/HDX. operationId: GetHumanitarianSummary parameters: - name: country_code in: query description: ISO 3166-1 alpha-2 country code (e.g., "YE", "SD", "SO"). required: false schema: type: string responses: "200": description: Successful response content: application/json: schema: $ref: '#/components/schemas/GetHumanitarianSummaryResponse' "400": description: Validation error content: application/json: schema: $ref: '#/components/schemas/ValidationError' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/Error' /api/conflict/v1/list-iran-events: get: tags: - ConflictService summary: ListIranEvents description: ListIranEvents retrieves scraped conflict events from LiveUAMap Iran. operationId: ListIranEvents responses: "200": description: Successful response content: application/json: schema: $ref: '#/components/schemas/ListIranEventsResponse' "400": description: Validation error content: application/json: schema: $ref: '#/components/schemas/ValidationError' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/Error' /api/conflict/v1/get-humanitarian-summary-batch: post: tags: - ConflictService summary: GetHumanitarianSummaryBatch description: GetHumanitarianSummaryBatch retrieves humanitarian summaries for multiple countries in one call. operationId: GetHumanitarianSummaryBatch requestBody: content: application/json: schema: $ref: '#/components/schemas/GetHumanitarianSummaryBatchRequest' required: true responses: "200": description: Successful response content: application/json: schema: $ref: '#/components/schemas/GetHumanitarianSummaryBatchResponse' "400": description: Validation error content: application/json: schema: $ref: '#/components/schemas/ValidationError' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: Error: type: object properties: message: type: string description: Error message (e.g., 'user not found', 'database connection failed') description: Error is returned when a handler encounters an error. It contains a simple error message that the developer can customize. FieldViolation: type: object properties: field: type: string description: The field path that failed validation (e.g., 'user.email' for nested fields). For header validation, this will be the header name (e.g., 'X-API-Key') description: type: string description: Human-readable description of the validation violation (e.g., 'must be a valid email address', 'required field missing') required: - field - description description: FieldViolation describes a single validation error for a specific field. ValidationError: type: object properties: violations: type: array items: $ref: '#/components/schemas/FieldViolation' description: List of validation violations required: - violations description: ValidationError is returned when request validation fails. It contains a list of field violations describing what went wrong. ListAcledEventsRequest: type: object properties: start: type: integer format: int64 description: 'Start of time range (inclusive), Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript' end: type: integer format: int64 description: 'End of time range (inclusive), Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript' pageSize: type: integer format: int32 description: Maximum items per page (1-100). cursor: type: string description: Cursor for next page. country: type: string description: Optional country filter (ISO 3166-1 alpha-2). description: ListAcledEventsRequest specifies filters for retrieving ACLED conflict events. ListAcledEventsResponse: type: object properties: events: type: array items: $ref: '#/components/schemas/AcledConflictEvent' pagination: $ref: '#/components/schemas/PaginationResponse' description: ListAcledEventsResponse contains ACLED conflict events matching the request. AcledConflictEvent: type: object properties: id: type: string minLength: 1 description: Unique ACLED event identifier. eventType: type: string description: ACLED event type classification (e.g., "Battles", "Explosions/Remote violence"). country: type: string description: Country where the event occurred. location: $ref: '#/components/schemas/GeoCoordinates' occurredAt: type: integer format: int64 description: 'Time the event occurred, as Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript' fatalities: type: integer format: int32 description: Reported fatalities from this event. actors: type: array items: type: string description: Named actors involved in the event. source: type: string description: Source article or report. admin1: type: string description: Administrative region within the country. required: - id description: AcledConflictEvent represents an armed conflict event from the ACLED dataset. GeoCoordinates: type: object properties: latitude: type: number maximum: 90 minimum: -90 format: double description: Latitude in decimal degrees (-90 to 90). longitude: type: number maximum: 180 minimum: -180 format: double description: Longitude in decimal degrees (-180 to 180). description: GeoCoordinates represents a geographic location using WGS84 coordinates. PaginationResponse: type: object properties: nextCursor: type: string description: Cursor for fetching the next page. Empty string indicates no more pages. totalCount: type: integer format: int32 description: Total count of items matching the query, if known. Zero if the total is unknown. description: PaginationResponse contains pagination metadata returned alongside list results. ListUcdpEventsRequest: type: object properties: start: type: integer format: int64 description: 'Start of time range (inclusive), Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript' end: type: integer format: int64 description: 'End of time range (inclusive), Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript' pageSize: type: integer format: int32 description: Maximum items per page (1-100). cursor: type: string description: Cursor for next page. country: type: string description: Optional country filter (ISO 3166-1 alpha-2). description: ListUcdpEventsRequest specifies filters for retrieving UCDP violence events. ListUcdpEventsResponse: type: object properties: events: type: array items: $ref: '#/components/schemas/UcdpViolenceEvent' pagination: $ref: '#/components/schemas/PaginationResponse' description: ListUcdpEventsResponse contains UCDP violence events matching the request. UcdpViolenceEvent: type: object properties: id: type: string minLength: 1 description: Unique UCDP event identifier. dateStart: type: integer format: int64 description: 'Start date of the event, as Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript' dateEnd: type: integer format: int64 description: 'End date of the event, as Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript' location: $ref: '#/components/schemas/GeoCoordinates' country: type: string description: Country where the event occurred. sideA: type: string description: Primary party in the conflict (Side A). sideB: type: string description: Secondary party in the conflict (Side B). deathsBest: type: integer format: int32 description: Best estimate of deaths. deathsLow: type: integer format: int32 description: Low estimate of deaths. deathsHigh: type: integer format: int32 description: High estimate of deaths. violenceType: type: string enum: - UCDP_VIOLENCE_TYPE_UNSPECIFIED - UCDP_VIOLENCE_TYPE_STATE_BASED - UCDP_VIOLENCE_TYPE_NON_STATE - UCDP_VIOLENCE_TYPE_ONE_SIDED description: |- UcdpViolenceType represents the UCDP violence classification. Maps to existing TS union: 'state-based' | 'non-state' | 'one-sided'. sourceOriginal: type: string description: Original source of the event report. required: - id description: UcdpViolenceEvent represents a georeferenced violence event from the UCDP dataset. GetHumanitarianSummaryRequest: type: object properties: countryCode: type: string pattern: ^[A-Z]{2}$ description: ISO 3166-1 alpha-2 country code (e.g., "YE", "SD", "SO"). required: - countryCode description: GetHumanitarianSummaryRequest specifies which country to retrieve the humanitarian summary for. GetHumanitarianSummaryResponse: type: object properties: summary: $ref: '#/components/schemas/HumanitarianCountrySummary' description: GetHumanitarianSummaryResponse contains the humanitarian summary for the requested country. HumanitarianCountrySummary: type: object properties: countryCode: type: string description: ISO 3166-1 alpha-2 country code. countryName: type: string description: Country name. conflictEventsTotal: type: integer format: int32 description: Total conflict events in the reference period. conflictPoliticalViolenceEvents: type: integer format: int32 description: Political violence + civilian targeting event count. conflictFatalities: type: integer format: int32 description: Total fatalities from political violence and civilian targeting. referencePeriod: type: string description: Reference period start date (YYYY-MM-DD). conflictDemonstrations: type: integer format: int32 description: Number of demonstration events. updatedAt: type: integer format: int64 description: 'Last data update time, as Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript' description: HumanitarianCountrySummary represents HAPI conflict event counts for a country. ListIranEventsRequest: type: object ListIranEventsResponse: type: object properties: events: type: array items: $ref: '#/components/schemas/IranEvent' scrapedAt: type: string format: int64 IranEvent: type: object properties: id: type: string title: type: string category: type: string sourceUrl: type: string latitude: type: number format: double longitude: type: number format: double locationName: type: string timestamp: type: string format: int64 severity: type: string GetHumanitarianSummaryBatchRequest: type: object properties: countryCodes: type: array items: type: string maxItems: 25 minItems: 1 description: ISO 3166-1 alpha-2 country codes (e.g., "YE", "SD"). Max 25. maxItems: 25 minItems: 1 description: GetHumanitarianSummaryBatchRequest looks up humanitarian summaries for multiple countries. GetHumanitarianSummaryBatchResponse: type: object properties: results: type: object additionalProperties: $ref: '#/components/schemas/HumanitarianCountrySummary' description: Map of country_code -> humanitarian summary for found countries. fetched: type: integer format: int32 description: Number of countries successfully fetched. requested: type: integer format: int32 description: Number of countries requested. description: GetHumanitarianSummaryBatchResponse contains humanitarian summaries for the requested countries. ResultsEntry: type: object properties: key: type: string value: $ref: '#/components/schemas/HumanitarianCountrySummary'