openapi: 3.1.0
info:
    title: DisplacementService API
    version: 1.0.0
paths:
    /api/displacement/v1/get-displacement-summary:
        get:
            tags:
                - DisplacementService
            summary: GetDisplacementSummary
            description: GetDisplacementSummary retrieves global refugee and IDP statistics from UNHCR.
            operationId: GetDisplacementSummary
            parameters:
                - name: year
                  in: query
                  description: Data year to retrieve (e.g., 2023). Uses latest available if zero.
                  required: false
                  schema:
                    type: integer
                    format: int32
                - name: country_limit
                  in: query
                  description: Maximum number of country entries to return.
                  required: false
                  schema:
                    type: integer
                    format: int32
                - name: flow_limit
                  in: query
                  description: Maximum number of displacement flows to return.
                  required: false
                  schema:
                    type: integer
                    format: int32
            responses:
                "200":
                    description: Successful response
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/GetDisplacementSummaryResponse'
                "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/displacement/v1/get-population-exposure:
        get:
            tags:
                - DisplacementService
            summary: GetPopulationExposure
            description: GetPopulationExposure returns country population data or estimates population within a radius.
            operationId: GetPopulationExposure
            parameters:
                - name: mode
                  in: query
                  description: 'Mode: "countries" (default) or "exposure".'
                  required: false
                  schema:
                    type: string
                - name: lat
                  in: query
                  description: Latitude (required for exposure mode).
                  required: false
                  schema:
                    type: number
                    format: double
                - name: lon
                  in: query
                  description: Longitude (required for exposure mode).
                  required: false
                  schema:
                    type: number
                    format: double
                - name: radius
                  in: query
                  description: Radius in km (required for exposure mode, defaults to 50).
                  required: false
                  schema:
                    type: number
                    format: double
            responses:
                "200":
                    description: Successful response
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/GetPopulationExposureResponse'
                "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.
        GetDisplacementSummaryRequest:
            type: object
            properties:
                year:
                    type: integer
                    minimum: 0
                    format: int32
                    description: Data year to retrieve (e.g., 2023). Uses latest available if zero.
                countryLimit:
                    type: integer
                    minimum: 0
                    format: int32
                    description: Maximum number of country entries to return.
                flowLimit:
                    type: integer
                    minimum: 0
                    format: int32
                    description: Maximum number of displacement flows to return.
            description: GetDisplacementSummaryRequest specifies parameters for retrieving displacement data.
        GetDisplacementSummaryResponse:
            type: object
            properties:
                summary:
                    $ref: '#/components/schemas/DisplacementSummary'
            description: GetDisplacementSummaryResponse contains the global displacement summary.
        DisplacementSummary:
            type: object
            properties:
                year:
                    type: integer
                    format: int32
                    description: Data year.
                globalTotals:
                    $ref: '#/components/schemas/GlobalDisplacementTotals'
                countries:
                    type: array
                    items:
                        $ref: '#/components/schemas/CountryDisplacement'
                topFlows:
                    type: array
                    items:
                        $ref: '#/components/schemas/DisplacementFlow'
            description: DisplacementSummary represents a global overview of displacement data from UNHCR.
        GlobalDisplacementTotals:
            type: object
            properties:
                refugees:
                    type: integer
                    minimum: 0
                    format: int64
                    description: 'Total recognized refugees worldwide.. Warning: Values > 2^53 may lose precision in JavaScript'
                asylumSeekers:
                    type: integer
                    minimum: 0
                    format: int64
                    description: 'Total asylum seekers worldwide.. Warning: Values > 2^53 may lose precision in JavaScript'
                idps:
                    type: integer
                    minimum: 0
                    format: int64
                    description: 'Total internally displaced persons worldwide.. Warning: Values > 2^53 may lose precision in JavaScript'
                stateless:
                    type: integer
                    minimum: 0
                    format: int64
                    description: 'Total stateless persons worldwide.. Warning: Values > 2^53 may lose precision in JavaScript'
                total:
                    type: integer
                    minimum: 0
                    format: int64
                    description: 'Grand total of displaced persons.. Warning: Values > 2^53 may lose precision in JavaScript'
            description: GlobalDisplacementTotals represents worldwide displacement figures.
        CountryDisplacement:
            type: object
            properties:
                code:
                    type: string
                    minLength: 1
                    description: ISO 3166-1 alpha-2 country code.
                name:
                    type: string
                    description: Country name.
                refugees:
                    type: integer
                    format: int64
                    description: 'Refugees originating from this country.. Warning: Values > 2^53 may lose precision in JavaScript'
                asylumSeekers:
                    type: integer
                    format: int64
                    description: 'Asylum seekers from this country.. Warning: Values > 2^53 may lose precision in JavaScript'
                idps:
                    type: integer
                    format: int64
                    description: 'Internally displaced persons within this country.. Warning: Values > 2^53 may lose precision in JavaScript'
                stateless:
                    type: integer
                    format: int64
                    description: 'Stateless persons associated with this country.. Warning: Values > 2^53 may lose precision in JavaScript'
                totalDisplaced:
                    type: integer
                    format: int64
                    description: 'Total displaced from this country.. Warning: Values > 2^53 may lose precision in JavaScript'
                hostRefugees:
                    type: integer
                    format: int64
                    description: 'Refugees hosted by this country.. Warning: Values > 2^53 may lose precision in JavaScript'
                hostAsylumSeekers:
                    type: integer
                    format: int64
                    description: 'Asylum seekers hosted by this country.. Warning: Values > 2^53 may lose precision in JavaScript'
                hostTotal:
                    type: integer
                    format: int64
                    description: 'Total persons hosted by this country.. Warning: Values > 2^53 may lose precision in JavaScript'
                location:
                    $ref: '#/components/schemas/GeoCoordinates'
            required:
                - code
            description: CountryDisplacement represents displacement metrics for a single country.
        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.
        DisplacementFlow:
            type: object
            properties:
                originCode:
                    type: string
                    minLength: 1
                    description: ISO 3166-1 alpha-2 code of the origin country.
                originName:
                    type: string
                    description: Origin country name.
                asylumCode:
                    type: string
                    minLength: 1
                    description: ISO 3166-1 alpha-2 code of the asylum country.
                asylumName:
                    type: string
                    description: Asylum country name.
                refugees:
                    type: integer
                    format: int64
                    description: 'Number of refugees in this flow.. Warning: Values > 2^53 may lose precision in JavaScript'
                originLocation:
                    $ref: '#/components/schemas/GeoCoordinates'
                asylumLocation:
                    $ref: '#/components/schemas/GeoCoordinates'
            required:
                - originCode
                - asylumCode
            description: DisplacementFlow represents a refugee movement corridor between two countries.
        GetPopulationExposureRequest:
            type: object
            properties:
                mode:
                    type: string
                    description: 'Mode: "countries" (default) or "exposure".'
                lat:
                    type: number
                    maximum: 90
                    minimum: -90
                    format: double
                    description: Latitude (required for exposure mode).
                lon:
                    type: number
                    maximum: 180
                    minimum: -180
                    format: double
                    description: Longitude (required for exposure mode).
                radius:
                    type: number
                    minimum: 0
                    format: double
                    description: Radius in km (required for exposure mode, defaults to 50).
            description: |-
                GetPopulationExposureRequest supports two modes:
                 - countries mode (default): returns the priority countries list
                 - exposure mode: estimates population within a radius of a point
        GetPopulationExposureResponse:
            type: object
            properties:
                success:
                    type: boolean
                    description: True if the request succeeded.
                countries:
                    type: array
                    items:
                        $ref: '#/components/schemas/CountryPopulationEntry'
                exposure:
                    $ref: '#/components/schemas/ExposureResult'
            description: GetPopulationExposureResponse returns either a countries list or an exposure estimate.
        CountryPopulationEntry:
            type: object
            properties:
                code:
                    type: string
                    description: ISO 3166-1 alpha-3 country code.
                name:
                    type: string
                    description: Country name.
                population:
                    type: integer
                    format: int64
                    description: 'Total population.. Warning: Values > 2^53 may lose precision in JavaScript'
                densityPerKm2:
                    type: integer
                    format: int32
                    description: Population density per square kilometer.
            description: CountryPopulationEntry represents a country with population data.
        ExposureResult:
            type: object
            properties:
                exposedPopulation:
                    type: integer
                    format: int64
                    description: 'Estimated exposed population.. Warning: Values > 2^53 may lose precision in JavaScript'
                exposureRadiusKm:
                    type: number
                    format: double
                    description: Radius used for the estimate in km.
                nearestCountry:
                    type: string
                    description: ISO3 code of nearest priority country.
                densityPerKm2:
                    type: integer
                    format: int32
                    description: Population density used for the estimate.
            description: ExposureResult contains the population exposure estimate.
