openapi: 3.0.3
info:
  title: Global System for Mobile Communications GSMA Camara Project Endpoint Discovery Application Population Density Data API
  version: 0.1.0-wip
  description: The Application Discovery API extends beyond the capabilities of the Simple Edge Discovery API by not only locating the nearest Edge Cloud Zone but also directly linking to the application endpoints within those Edge Cloud Zones.
  contact:
    email: sp-edc@lists.camaraproject.org
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: '{apiRoot}/{basePath}'
  variables:
    apiRoot:
      default: https://localhost:443
      description: API root.
    basePath:
      default: application-endpoint-discovery/vwip
      description: Base path for the Application Endpoint Discovery.
tags:
- name: Population Density Data
  description: Operations to retrieve population density information.
paths:
  /retrieve:
    post:
      tags:
      - Population Density Data
      summary: Global System for Mobile Communications Retrieves population density information in a specified area
      description: Retrieves population density estimation together with the estimation range related  for a time slot for a given area (described as a polygon) as a data set consisting of a sequence of equally-sized objects covering the input polygon area.
      operationId: retrievePopulationDensity
      parameters:
      - $ref: '#/components/parameters/x-correlator'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PopulationDensityRequest'
            example:
              area:
                areaType: POLYGON
                boundary:
                - latitude: 45.754114
                  longitude: 4.860374
                - latitude: 45.753845
                  longitude: 4.863185
                - latitude: 45.75249
                  longitude: 4.861876
                - latitude: 45.751224
                  longitude: 4.861125
                - latitude: 45.751442
                  longitude: 4.859827
              startDate: '2024-04-23T14:44:18.165Z'
              endDate: '2024-04-23T14:44:18.165Z'
              precision: 7
        required: true
      callbacks:
        populationDensityDataCallback:
          '{$request.body#/sink}':
            post:
              tags:
              - Population Density Data
              summary: Population Density Data callback
              description: 'Important: this endpoint is to be implemented by the API consumer.

                The Population Density Data server will call this endpoint when the request result is ready.

                '
              operationId: postNotification
              parameters:
              - $ref: '#/components/parameters/x-correlator'
              requestBody:
                description: Population density data result.
                content:
                  application/json:
                    schema:
                      $ref: '#/components/schemas/PopulationDensityResponse'
                    examples:
                      PopulationDensitySupportedAreaResponseExample:
                        $ref: '#/components/examples/PopulationDensitySupportedAreaResponseExample'
                      PopulationDensityAreaNotSupportedResponseExample:
                        $ref: '#/components/examples/PopulationDensityAreaNotSupportedResponseExample'
                      PopulationDensityPartOfAreaNotSupportedResponseExample:
                        $ref: '#/components/examples/PopulationDensityPartOfAreaNotSupportedResponseExample'
              responses:
                '204':
                  description: Successful notification
                  headers:
                    x-correlator:
                      $ref: '#/components/headers/x-correlator'
                '400':
                  $ref: '#/components/responses/Generic400'
                '401':
                  $ref: '#/components/responses/Generic401'
                '403':
                  $ref: '#/components/responses/Generic403'
                '410':
                  $ref: '#/components/responses/Generic410'
                '500':
                  $ref: '#/components/responses/Generic500'
                '503':
                  $ref: '#/components/responses/Generic503'
              security:
              - {}
              - notificationsBearerAuth: []
      responses:
        '200':
          description: Population density data result.
          headers:
            x-correlator:
              $ref: '#/components/headers/x-correlator'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PopulationDensityResponse'
              examples:
                PopulationDensitySupportedAreaResponseExample:
                  $ref: '#/components/examples/PopulationDensitySupportedAreaResponseExample'
                PopulationDensityAreaNotSupportedResponseExample:
                  $ref: '#/components/examples/PopulationDensityAreaNotSupportedResponseExample'
                PopulationDensityPartOfAreaNotSupportedResponseExample:
                  $ref: '#/components/examples/PopulationDensityPartOfAreaNotSupportedResponseExample'
        '202':
          description: Population density data requested. This response is returned when the behaviour of the API is asynchronous.
          headers:
            x-correlator:
              $ref: '#/components/headers/x-correlator'
        '400':
          $ref: '#/components/responses/RetrieveLocationBadRequest400'
        '401':
          $ref: '#/components/responses/Generic401'
        '403':
          $ref: '#/components/responses/Generic403'
        '404':
          $ref: '#/components/responses/Generic404'
        '500':
          $ref: '#/components/responses/Generic500'
        '503':
          $ref: '#/components/responses/Generic503'
      security:
      - openId:
        - population-density-data:read
components:
  responses:
    Generic503:
      description: Service unavailable
      headers:
        x-correlator:
          $ref: '#/components/headers/x-correlator'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          example:
            status: 503
            code: UNAVAILABLE
            message: Service unavailable
    Generic500:
      description: Internal server error
      headers:
        x-correlator:
          $ref: '#/components/headers/x-correlator'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          example:
            status: 500
            code: INTERNAL
            message: Internal server error
    Generic410:
      description: Gone
      headers:
        x-correlator:
          $ref: '#/components/headers/x-correlator'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          examples:
            GENERIC_410_GONE:
              description: Use in notifications flow to allow API Consumer to indicate that its callback is no longer available
              value:
                status: 410
                code: GONE
                message: Access to the target resource is no longer available.
    Generic400:
      description: Problem with the client request
      headers:
        x-correlator:
          $ref: '#/components/headers/x-correlator'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          example:
            status: 400
            code: INVALID_ARGUMENT
            message: Client specified an invalid argument, request body or query param
    RetrieveLocationBadRequest400:
      description: "Problem with the client request. In addition to generic scenarios of `INVALID_ARGUMENT`, `INVALID_CREDENTIAL`, `INVALID_TOKEN`, another scenarios may exist:\n  - The area is not a polygon shape or exceeds supported complexity (\"code\": \"POPULATION_DENSITY_DATA.INVALID_AREA\", \"message\": \"The area is not a polygon shape or exceeds supported complexity\")\n  - Indicated combination of area, time interval and precision is too big (\"code\": \"POPULATION_DENSITY_DATA.UNSUPPPORTED_REQUEST\", \"message\": \"Indicated combination of area, time interval and precision is too big\")\n  - Indicated `startDate` is greater than the maximum allowed (\"code\": \"POPULATION_DENSITY_DATA.MAX_STARTDATE_EXCEEDED\", \"message\": \"Indicated startDate is greater than the maximum allowed\")\n  - Indicated `startDate` is earlier than the minimum allowed (\"code\": \"POPULATION_DENSITY_DATA.MIN_STARTDATE_EXCEEDED\", \"message\": \"Indicated startDate is earlier than the minimum allowed\")\n  - Indicated `endDate` is earlier than the `startDate` (\"code\": \"POPULATION_DENSITY_DATA.INVALID_END_DATE\", \"message\": \"Indicated endDate is earlier than the startDate\")\n  - Indicated time period is greater than the maximum allowed (More than maximum hours between startDate and endDate) (\"code\": \"POPULATION_DENSITY_DATA.MAX_TIME_PERIOD_EXCEEDED\", \"message\": \"Indicated time period is greater than the maximum allowed (More than maximum hours between startDate and endDate)\")\n  - Indicated cell precision (Geohash level) is not supported (\"code\": \"POPULATION_DENSITY_DATA.UNSUPPORTED_PRECISION\", \"message\": \"Indicated cell precision (Geohash level) is not supported\")\n  - Indicated combination of area, time interval and precision is too big for a sync response (\"code\": \"POPULATION_DENSITY_DATA.UNSUPPORTED_SYNC_RESPONSE\", \"message\": \"Indicated combination of area, time interval and precision is too big for a sync response\")"
      headers:
        x-correlator:
          $ref: '#/components/headers/x-correlator'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          examples:
            InvalidArgument:
              value:
                status: 400
                code: INVALID_ARGUMENT
                message: Invalid input
            GENERIC_400_INVALID_CREDENTIAL:
              value:
                status: 400
                code: INVALID_CREDENTIAL
                message: Only Access token is supported
            GENERIC_400_INVALID_TOKEN:
              value:
                status: 400
                code: INVALID_TOKEN
                message: Only bearer token is supported
            InvalidAreaIssue:
              value:
                status: 400
                code: POPULATION_DENSITY_DATA.INVALID_AREA
                message: The area is not a polygon shape or has an arbitrary complexity
            UnsupportedRequestIssue:
              value:
                status: 400
                code: POPULATION_DENSITY_DATA.UNSUPPPORTED_REQUEST
                message: Indicated combination of area, time interval and precision is too big
            MaxStartDateIssue:
              value:
                status: 400
                code: POPULATION_DENSITY_DATA.MAX_STARTDATE_EXCEEDED
                message: Indicated startDate is greater than the maximum allowed
            MinStartDateIssue:
              value:
                status: 400
                code: POPULATION_DENSITY_DATA.MIN_STARTDATE_EXCEEDED
                message: Indicated startDate is earlier than the minimum allowed
            InvalidEndDateIssue:
              value:
                status: 400
                code: POPULATION_DENSITY_DATA.INVALID_END_DATE
                message: Indicated endDate is earlier than the startDate
            MaxDurationIssue:
              value:
                status: 400
                code: POPULATION_DENSITY_DATA.MAX_TIME_PERIOD_EXCEEDED
                message: Indicated time period is greater than the maximum allowed (More than maximum hours between startDate and endDate)
            PrecisionNotSupportedIssue:
              value:
                status: 400
                code: POPULATION_DENSITY_DATA.UNSUPPORTED_PRECISION
                message: Indicated cell precision (Geohash length) is not supported
            UnsupportedSyncResponseIssue:
              value:
                status: 400
                code: POPULATION_DENSITY_DATA.UNSUPPORTED_SYNC_RESPONSE
                message: Indicated combination of area, time interval and precision is too big for a sync response
    Generic401:
      description: Unauthorized
      headers:
        x-correlator:
          $ref: '#/components/headers/x-correlator'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          example:
            status: 401
            code: UNAUTHENTICATED
            message: 'Authorization failed: ...'
    Generic403:
      description: Forbidden
      headers:
        x-correlator:
          $ref: '#/components/headers/x-correlator'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          example:
            status: 403
            code: PERMISSION_DENIED
            message: 'Operation not allowed: ...'
    Generic404:
      description: Not found
      headers:
        x-correlator:
          $ref: '#/components/headers/x-correlator'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          example:
            status: 404
            code: NOT_FOUND
            message: The specified resource is not found
  parameters:
    x-correlator:
      name: x-correlator
      in: header
      description: Correlation id for the different services.
      schema:
        type: string
  examples:
    PopulationDensitySupportedAreaResponseExample:
      value:
        status: SUPPORTED_AREA
        timedPopulationDensityData:
        - startTime: '2024-01-03T10:00:00Z'
          endTime: '2024-01-03T11:00:00Z'
          cellPopulationDensityData:
          - geohash: ezdqemf
            populationDensityData:
              dataType: DENSITY_ESTIMATION
              maxPplDensity: 150
              minPplDensity: 30
              pplDensity: 60
          - geohash: ezdqemg
            populationDensityData:
              dataType: DENSITY_ESTIMATION
              maxPplDensity: 100
              minPplDensity: 40
              pplDensity: 90
          - geohash: ezdqemu
            populationDensityData:
              dataType: LOW_DENSITY
        - startTime: '2024-01-03T11:00:00Z'
          endTime: '2024-01-03T12:00:00Z'
          cellPopulationDensityData:
          - geohash: ezdqemf
            populationDensityData:
              dataType: DENSITY_ESTIMATION
              maxPplDensity: 100
              minPplDensity: 30
              pplDensity: 70
          - geohash: ezdqemg
            populationDensityData:
              dataType: DENSITY_ESTIMATION
              maxPplDensity: 200
              minPplDensity: 40
              pplDensity: 100
          - geohash: ezdqemu
            populationDensityData:
              dataType: DENSITY_ESTIMATION
              maxPplDensity: 200
              minPplDensity: 40
              pplDensity: 100
    PopulationDensityAreaNotSupportedResponseExample:
      value:
        status: AREA_NOT_SUPPORTED
        timedPopulationDensityData: []
    PopulationDensityPartOfAreaNotSupportedResponseExample:
      value:
        status: PART_OF_AREA_NOT_SUPPORTED
        timedPopulationDensityData:
        - startTime: '2024-01-03T10:00:00Z'
          endTime: '2024-01-03T11:00:00Z'
          cellPopulationDensityData:
          - geohash: ezdqemf
            populationDensityData:
              dataType: DENSITY_ESTIMATION
              maxPplDensity: 150
              minPplDensity: 30
              pplDensity: 60
          - geohash: ezdqemg
            populationDensityData:
              dataType: DENSITY_ESTIMATION
              maxPplDensity: 100
              minPplDensity: 40
              pplDensity: 90
          - geohash: ezdqemu
            populationDensityData:
              dataType: NO_DATA
        - startTime: '2024-01-03T11:00:00Z'
          endTime: '2024-01-03T12:00:00Z'
          cellPopulationDensityData:
          - geohash: ezdqemf
            populationDensityData:
              dataType: DENSITY_ESTIMATION
              maxPplDensity: 100
              minPplDensity: 30
              pplDensity: 70
          - geohash: ezdqemg
            populationDensityData:
              dataType: DENSITY_ESTIMATION
              maxPplDensity: 200
              minPplDensity: 40
              pplDensity: 100
          - geohash: ezdqemu
            populationDensityData:
              dataType: NO_DATA
  schemas:
    AreaType:
      type: string
      description: 'Type of this area.

        POLYGON - The area is defined as a polygon.

        '
      enum:
      - POLYGON
    PopulationDensityRequest:
      type: object
      description: 'Request object for retrieving population density data in a specified area. **NOTE**: The difference between `startDate` and `endDate` cannot be greater than 7 days.'
      properties:
        area:
          $ref: '#/components/schemas/Area'
        startDate:
          type: string
          format: date-time
          description: Start date time. It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone. Recommended format is yyyy-MM-dd'T'HH:mm:ss.SSSZ  (i.e. which allows 2023-07-03T14:27:08.312+02:00 or 2023-07-03T12:27:08.312Z) The minimum startDate is the time of the request.
        endDate:
          type: string
          format: date-time
          description: End date time. It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone. Recommended format is yyyy-MM-dd'T'HH:mm:ss.SSSZ (i.e. which allows 2023-07-03T14:27:08.312+02:00 or 2023-07-03T12:27:08.312Z) The maximum endDate allowed is 3 months from the time of the request.
        precision:
          type: integer
          description: Precision required of response cells. Precision defines a geohash level and corresponds to the length of the geohash for each cell. More information at [Geohash system](https://en.wikipedia.org/wiki/Geohash)" If not included the default precision level 7 is used by default. In case of using a not supported level by the MNO, the API returns the error response `POPULATION_DENSITY_DATA.UNSUPPORTED_PRECISION`.
          minimum: 1
          maximum: 12
          default: 7
        sink:
          type: string
          format: url
          description: The address to which events about all status changes of the session (e.g. session termination) shall be delivered, using the HTTP protocol.
          example: https://endpoint.example.com/sink
        sinkCredential:
          description: A sink credential provides authentication or authorization information necessary to enable delivery of events to a target.
          allOf:
          - $ref: '#/components/schemas/SinkCredential'
      required:
      - area
      - startDate
      - endDate
    PopulationDensityResponse:
      type: object
      description: Population density values is represented in time intervals for different  cells of the requested area. Each element in `timedPopulationDensityData` array corresponds  to a time interval, containing population density data for the grid cells. The intervals are 1 hour long.
      properties:
        timedPopulationDensityData:
          type: array
          description: "Time ranges along with the population density data for the cells within it.\n The request startDate or the request endDate have to be fully covered by the intervals.\n For example, if the intervals are 1-hour long and the input date range were [2024-01-03T11:25:00Z\n to 2024-01-03T12:45:00Z] it would contain 2 intervals (Interval from 2024-01-03T11:00:00Z\n to 2024-01-03T12:00:00Z and interval from 2024-01-03T12:00:00Z to 2024-01-03T13:00:00Z)."
          items:
            $ref: '#/components/schemas/TimedPopulationDensityData'
        status:
          $ref: '#/components/schemas/ResponseStatus'
      required:
      - timedPopulationDensityData
      - status
    Area:
      type: object
      properties:
        areaType:
          $ref: '#/components/schemas/AreaType'
      required:
      - areaType
      discriminator:
        propertyName: areaType
        mapping:
          POLYGON: '#/components/schemas/Polygon'
    ResponseStatus:
      type: string
      description: "Represents the state of the response for the input polygon defined in the request, the possible values are:\n  - `SUPPORTED_AREA`: The whole request area is supported. Population density data for the entire requested area is returned.\n  - `PART_OF_AREA_NOT_SUPPORTED`: Part of the requested area is outside the MNOs coverage area, the cells outside the coverage\n  area will have property `dataType` with value `NO_DATA`.\n  - `AREA_NOT_SUPPORTED`: The whole requested area is outside the MNOs coverage area. No data will be returned."
      enum:
      - SUPPORTED_AREA
      - PART_OF_AREA_NOT_SUPPORTED
      - AREA_NOT_SUPPORTED
    SinkCredential:
      type: object
      properties:
        credentialType:
          type: string
          enum:
          - PLAIN
          - ACCESSTOKEN
          - REFRESHTOKEN
          description: The type of the credential. With the current API version the type MUST be set to `ACCESSTOKEN`
      discriminator:
        propertyName: credentialType
        mapping:
          PLAIN: '#/components/schemas/PlainCredential'
          ACCESSTOKEN: '#/components/schemas/AccessTokenCredential'
          REFRESHTOKEN: '#/components/schemas/RefreshTokenCredential'
      required:
      - credentialType
    ErrorInfo:
      type: object
      required:
      - status
      - code
      - message
      properties:
        status:
          type: integer
          description: HTTP status code returned along with this error response.
        code:
          type: string
          description: Code given to this error.
        message:
          type: string
          description: Detailed error description.
    TimedPopulationDensityData:
      type: object
      properties:
        startTime:
          type: string
          format: date-time
          description: Interval start time. It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone. Recommended format is yyyy-MM-dd'T'HH:mm:ss.SSSZ (i.e. which allows 2023-07-03T14:27:08.312+02:00 or 2023-07-03T12:27:08.312Z)
        endTime:
          type: string
          format: date-time
          description: Interval end time. It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone. Recommended format is yyyy-MM-dd'T'HH:mm:ss.SSSZ (i.e. which allows 2023-07-03T14:27:08.312+02:00 or 2023-07-03T12:27:08.312Z)
          example: '2024-01-03T13:00:00Z'
        cellPopulationDensityData:
          $ref: '#/components/schemas/CellPopulationDensityDataArray'
      required:
      - startTime
      - endTime
      - cellPopulationDensityData
    CellPopulationDensityDataArray:
      type: array
      description: Population density data for the different cells in a concrete time range.
      items:
        $ref: '#/components/schemas/CellPopulationDensityData'
      minItems: 1
    PopulationDensityData:
      description: Object that contains the estimated population density and an estimation range in a cell for a specific time interval. In case of insufficient data to guarantee an anonymized prediction due to the k-anonymity within a specific cell and time range, no population density data is returned and the property `dataType` value is "LOW_DENSITY". In case of a cell not supported `dataType` value is "NO_DATA"
      properties:
        dataType:
          type: string
          enum:
          - NO_DATA
          - LOW_DENSITY
          - DENSITY_ESTIMATION
      required:
      - dataType
      discriminator:
        propertyName: dataType
        mapping:
          NO_DATA: '#/components/schemas/PopulationDensityData'
          LOW_DENSITY: '#/components/schemas/PopulationDensityData'
          DENSITY_ESTIMATION: '#/components/schemas/DensityEstimationPopulationDensityData'
    CellPopulationDensityData:
      type: object
      description: Population density data of a cell in a concrete time range.
      properties:
        geohash:
          type: string
          description: Coordinates of the cell represented as a string using the [Geohash system](https://en.wikipedia.org/wiki/Geohash). Encoding a geographic location into a short string. The value length, and thus, the cell granularity, is determined by the request body property `precision`.
          example: ezdmemd
        populationDensityData:
          $ref: '#/components/schemas/PopulationDensityData'
      required:
      - geohash
      - populationDensityData
  headers:
    x-correlator:
      description: Correlation id for the different services.
      schema:
        type: string
  securitySchemes:
    openId:
      description: OpenID Provider Configuration Information.
      type: openIdConnect
      openIdConnectUrl: .well-known/openid-configuration
externalDocs:
  description: Product documentation at CAMARA.
  url: https://github.com/camaraproject/EdgeCloud