ConflictService.openapi.yaml

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'