UnrestService.openapi.yaml

openapi: 3.1.0
info:
    title: UnrestService API
    version: 1.0.0
paths:
    /api/unrest/v1/list-unrest-events:
        get:
            tags:
                - UnrestService
            summary: ListUnrestEvents
            description: ListUnrestEvents retrieves protest, riot, and civil unrest events.
            operationId: ListUnrestEvents
            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
                - name: min_severity
                  in: query
                  description: Optional minimum severity filter.
                  required: false
                  schema:
                    type: string
                - name: ne_lat
                  in: query
                  description: North-east corner latitude of bounding box.
                  required: false
                  schema:
                    type: number
                    format: double
                - name: ne_lon
                  in: query
                  description: North-east corner longitude of bounding box.
                  required: false
                  schema:
                    type: number
                    format: double
                - name: sw_lat
                  in: query
                  description: South-west corner latitude of bounding box.
                  required: false
                  schema:
                    type: number
                    format: double
                - name: sw_lon
                  in: query
                  description: South-west corner longitude of bounding box.
                  required: false
                  schema:
                    type: number
                    format: double
            responses:
                "200":
                    description: Successful response
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ListUnrestEventsResponse'
                "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.
        ListUnrestEventsRequest:
            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).
                minSeverity:
                    type: string
                    enum:
                        - SEVERITY_LEVEL_UNSPECIFIED
                        - SEVERITY_LEVEL_LOW
                        - SEVERITY_LEVEL_MEDIUM
                        - SEVERITY_LEVEL_HIGH
                    description: |-
                        SeverityLevel represents a three-tier severity classification used across domains.
                         Maps to existing TS unions: 'low' | 'medium' | 'high'.
                neLat:
                    type: number
                    format: double
                    description: North-east corner latitude of bounding box.
                neLon:
                    type: number
                    format: double
                    description: North-east corner longitude of bounding box.
                swLat:
                    type: number
                    format: double
                    description: South-west corner latitude of bounding box.
                swLon:
                    type: number
                    format: double
                    description: South-west corner longitude of bounding box.
            description: ListUnrestEventsRequest specifies filters for retrieving social unrest events.
        ListUnrestEventsResponse:
            type: object
            properties:
                events:
                    type: array
                    items:
                        $ref: '#/components/schemas/UnrestEvent'
                clusters:
                    type: array
                    items:
                        $ref: '#/components/schemas/UnrestCluster'
                pagination:
                    $ref: '#/components/schemas/PaginationResponse'
            description: ListUnrestEventsResponse contains unrest events and clusters matching the request.
        UnrestEvent:
            type: object
            properties:
                id:
                    type: string
                    minLength: 1
                    description: Unique event identifier.
                title:
                    type: string
                    description: Event title or headline.
                summary:
                    type: string
                    description: Brief summary of the event.
                eventType:
                    type: string
                    enum:
                        - UNREST_EVENT_TYPE_UNSPECIFIED
                        - UNREST_EVENT_TYPE_PROTEST
                        - UNREST_EVENT_TYPE_RIOT
                        - UNREST_EVENT_TYPE_STRIKE
                        - UNREST_EVENT_TYPE_DEMONSTRATION
                        - UNREST_EVENT_TYPE_CIVIL_UNREST
                    description: |-
                        UnrestEventType represents the classification of a social unrest event.
                         Maps to existing TS union: 'protest' | 'riot' | 'strike' | 'demonstration' | 'civil_unrest'.
                city:
                    type: string
                    description: City where the event occurred.
                country:
                    type: string
                    description: Country where the event occurred.
                region:
                    type: string
                    description: Administrative region within the country.
                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'
                severity:
                    type: string
                    enum:
                        - SEVERITY_LEVEL_UNSPECIFIED
                        - SEVERITY_LEVEL_LOW
                        - SEVERITY_LEVEL_MEDIUM
                        - SEVERITY_LEVEL_HIGH
                    description: |-
                        SeverityLevel represents a three-tier severity classification used across domains.
                         Maps to existing TS unions: 'low' | 'medium' | 'high'.
                fatalities:
                    type: integer
                    format: int32
                    description: Reported fatalities, if any.
                sources:
                    type: array
                    items:
                        type: string
                        description: Source identifiers.
                sourceType:
                    type: string
                    enum:
                        - UNREST_SOURCE_TYPE_UNSPECIFIED
                        - UNREST_SOURCE_TYPE_ACLED
                        - UNREST_SOURCE_TYPE_GDELT
                        - UNREST_SOURCE_TYPE_RSS
                    description: |-
                        UnrestSourceType represents the data source for an unrest event.
                         Maps to existing TS union: 'acled' | 'gdelt' | 'rss'.
                tags:
                    type: array
                    items:
                        type: string
                        description: Descriptive tags.
                actors:
                    type: array
                    items:
                        type: string
                        description: Named actors involved.
                confidence:
                    type: string
                    enum:
                        - CONFIDENCE_LEVEL_UNSPECIFIED
                        - CONFIDENCE_LEVEL_LOW
                        - CONFIDENCE_LEVEL_MEDIUM
                        - CONFIDENCE_LEVEL_HIGH
                    description: |-
                        ConfidenceLevel represents the confidence in event data accuracy.
                         Used across multiple domains.
            required:
                - id
            description: |-
                UnrestEvent represents a social unrest incident (protest, riot, strike, etc.).
                 Aggregated from ACLED and GDELT sources.
        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.
        UnrestCluster:
            type: object
            properties:
                id:
                    type: string
                    description: Unique cluster identifier.
                country:
                    type: string
                    description: Country of the cluster.
                region:
                    type: string
                    description: Region within the country.
                eventCount:
                    type: integer
                    format: int32
                    description: Number of events in this cluster.
                events:
                    type: array
                    items:
                        $ref: '#/components/schemas/UnrestEvent'
                severity:
                    type: string
                    enum:
                        - SEVERITY_LEVEL_UNSPECIFIED
                        - SEVERITY_LEVEL_LOW
                        - SEVERITY_LEVEL_MEDIUM
                        - SEVERITY_LEVEL_HIGH
                    description: |-
                        SeverityLevel represents a three-tier severity classification used across domains.
                         Maps to existing TS unions: 'low' | 'medium' | 'high'.
                startAt:
                    type: integer
                    format: int64
                    description: 'Start of the cluster time window, as Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript'
                endAt:
                    type: integer
                    format: int64
                    description: 'End of the cluster time window, as Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript'
                primaryCause:
                    type: string
                    description: Primary cause or theme of the unrest.
            description: UnrestCluster represents a geographic cluster of related unrest events.
        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.