CAMARA Population Density Data API

Aggregated, anonymized counts of mobile devices observed in a target geographic area over a time window. Powers smart-city planning, retail footfall analytics, event crowd management, and emergency response — without exposing any individual identifier.

CAMARA Population Density Data API is one of 15 APIs that CAMARA Project publishes on the APIs.io network, described by a machine-readable OpenAPI specification.

Tagged areas include Analytics, Network Insights, Population Density, and Telecom. The published artifact set on APIs.io includes API documentation and an OpenAPI specification.

OpenAPI Specification

population-density-data-openapi.yml Raw ↑
openapi: 3.0.3
info:
  title: Population Density Data
  description: >-
    The Population Density Data API exposes population density estimations
    for a specified area for a specified time interval.

    # Introduction

    With the Population Density Data API the customer can retrieve population density estimations
    for a specific area at the current or a specified period of time. The estimation considers historical
    anonymized information of the network connected devices in the requested
    area. * Note that the data provided are estimations of population, based on past or future predicted data, for both past or future time ranges.


    This functionality can be used for multiple use
    cases, some of the possible use cases for this API are:


    - Supporting BVLOS (Beyond Visual Line of Sight) flights with the
    information needed to meet SORA 2.5 (Specific Operation Risk Assessment)
    requirements in terms of intrinsic Ground Risk Class (iGRC).
    More information in [Specific Operations Risk Assessment](https://www.easa.europa.eu/en/domains/civil-drones-rpas/specific-category-civil-drones/specific-operations-risk-assessment-sora)

    - Providing information to identify if the ground risk class for
    a given drone flight path is acceptable for the time of the flight, or an
    alternative time should be considered to lower the risk.

    - Sustainable Urban Planning.

    - Environmental monitoring at mass events, such as concerts or festivals.


    The list above is just a few examples, the API can be used for other use cases as well.


    # Relevant terms and definitions

    * **Population Density**: refers to the number of people in a given area divided by the total size of the area.

    * **Notification URL and token**: Developers may provide a callback URL (`sink`) for receiving an async response.
    This is an optional parameter. If `sink` is included, it is RECOMMENDED for the client to provide as well the `sinkCredential`
    property to protect the notification endpoint. In the current version,`sinkCredential.credentialType` MUST be set to `ACCESSTOKEN` if provided.
    When an asynchronous response is requested, the 202 response of the API will include an `operationId` property. This `operationId` property will
    also be sent in the callback notification. The purpose of the `operationId` is to correlate an asynchronous response with its corresponding request.

    # API Functionality

    Once a developer specifies (1) the area as a polygon shape, (2) a precision level and (3) time interval
    in which they want to obtain the population density, the API returns a data
    set consisting of a sequence of time ranges, with each time range containing the
    input polygon subdivided into equal-sized grid cells.


    For each of the equal-sized cells of the grid, an estimated population density is
    reported for each time slot within the range, this includes: estimated population density people/km2, and a range for this estimation - [minimum, maximum]
    (exact definitions of minimum and maximum are estimation algorithm specific).


    These values are calculated based on historical data, prediction models, and population estimation models. The requested interval must either be completely in the future or in the past.

    The API has the following time constraints for requests: the minimum startTime must cover at least 3 months before the request time,
    and the maximum endTime allowed is 3 months from the time of the request.

    The polygon specifying an area of interest must comply with certain restrictions,
    which must be previously validated by the developer:

    - The polygon may not exceed a certain area.

    - The polygon may not contain more than 15 vertexes.

    - The polygon must be associated with a location where the MNO provides
    mobile connectivity services. If a polygon is located entirely outside the
    supported area, an empty array is returned.


    The standard behaviour of the API is synchronous, although for large
    area requests the API may behave asynchronously. An API invoker can enforce
    asynchronous behaviour by providing a callback URL (`sink`)
    is in the request, in this case the API sends a callback
    to the callback URL provided with the result of the request. If `sink` is
    included, it is RECOMMENDED for the client to provide as well the `sinkCredential`
    property to protect the notification endpoint. In the current version,`sinkCredential.credentialType`
    MUST be set to `ACCESSTOKEN` if provided.


    For requests with a combination of `area`, `precision`, `startTime` and `endTime`
    properties involving an amount of processing that cannot be processed synchronously,
    the API returns the error response `POPULATION_DENSITY_DATA.UNSUPPORTED_SYNC_RESPONSE`.


    For requests with a combination of `area`, `precision`, `startTime` and `endTime`
    properties too big for both synchronous and asynchronous processing, the API
    returns the error response `POPULATION_DENSITY_DATA.UNSUPPORTED_REQUEST`.

    If an error happens during the asynchronous processing of the request. The API callback
    will have property `status` with value `OPERATION_NOT_COMPLETED` as an error cannot be returned in the callback.
    The callback will also include the `statusInfo` property to add extra information about the error.

    **NOTE**: In order to ensure anonymized information, if the data relating to
    a grid cell in the required time interval is not sufficient to be exposed due
    to [k-anonymity](https://en.wikipedia.org/wiki/K-anonymity), no such data is
    returned by the API and the value of the dataType property is `LOW_DENSITY`.

    # Resources and Operations overview

    The API provides one endpoint that accepts POST requests for retrieving population
    density information in the specified area.

    # Authorization and authentication

    The "Camara Security and Interoperability Profile" provides details of how an API consumer requests an access token. Please refer to Identity and Consent Management (https://github.com/camaraproject/IdentityAndConsentManagement/) for the released version of the profile.

    The specific authorization flows to be used will be agreed upon during the onboarding process, happening between the API consumer and the API provider, taking into account the declared purpose for accessing the API, whilst also being subject to the prevailing legal framework dictated by local legislation.

    In cases where personal data is processed by the API and users can exercise their rights through mechanisms such as opt-in and/or opt-out, the use of three-legged access tokens is mandatory. This ensures that the API remains in compliance with privacy regulations, upholding the principles of transparency and user-centric privacy-by-design.

    Population Density Data API ensures the usage of anonymized information and do not treat personal data neither as input nor output.
    Therefore, the access to Population Density Data API is defined as Client Credentials - 2-legged. Please refer to Identify and Consent Management (https://github.com/camaraproject/IdentityAndConsentManagement/) for the latest detailed specification of this authentication/authorization flow.

    # Additional CAMARA error responses

    The list of error codes in this API specification is not exhaustive. Therefore the API specification may not document some non-mandatory error statuses as indicated in `CAMARA API Design Guide`.

    Please refer to the `CAMARA_common.yaml` of the Commonalities Release associated to this API version for a complete list of error responses. The applicable Commonalities Release can be identified in the `API Readiness Checklist` document associated to this API version.

    As a specific rule, error `501 - NOT_IMPLEMENTED` can be only a possible error response if it is explicitly documented in the API.

    # Further info and support

    (FAQs will be added in a later version of the documentation)

  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  version: wip

  x-camara-commonalities: 0.6
externalDocs:
  description: Product documentation at CAMARA.
  url: https://github.com/camaraproject/PopulationDensityData

servers:
  - url: '{apiRoot}/population-density-data/vwip'

    variables:
      apiRoot:
        default: http://localhost:9091
        description: API root
tags:
  - name: Population Density Data
    description: Operations to retrieve population density information.
paths:
  /retrieve:
    post:
      tags:
        - Population Density Data
      summary: 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
              startTime: '2024-04-23T14:44:18.165Z'
              endTime: '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/PopulationDensityAsyncResponse'
                    examples:
                      PopulationDensitySupportedAreaAsyncResponseExample:
                        $ref: '#/components/examples/PopulationDensitySupportedAreaAsyncResponseExample'
                      PopulationDensityAreaNotSupportedAsyncResponseExample:
                        $ref: '#/components/examples/PopulationDensityAreaNotSupportedAsyncResponseExample'
                      PopulationDensityPartOfAreaNotSupportedAsyncResponseExample:
                        $ref: '#/components/examples/PopulationDensityPartOfAreaNotSupportedAsyncResponseExample'
                      PopulationDensityOperationNotCompletedExample:
                        $ref: '#/components/examples/PopulationDensityOperationNotCompletedExample'
              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'
                '429':
                  $ref: '#/components/responses/Generic429'
              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'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AcceptedAsyncResponse'
        '400':
          $ref: '#/components/responses/RetrieveLocationBadRequest400'
        '401':
          $ref: '#/components/responses/Generic401'
        '403':
          $ref: '#/components/responses/Generic403'
        '404':
          $ref: '#/components/responses/Generic404'
        '422':
          $ref: '#/components/responses/RetrieveLocationUnprocessableContent422'
        '429':
          $ref: '#/components/responses/Generic429'
      security:
        - openId:
            - population-density-data:read
components:
  securitySchemes:
    openId:
      type: openIdConnect
      openIdConnectUrl: https://example.com/.well-known/openid-configuration
    notificationsBearerAuth:
      description: Bearer authentication for notifications
      type: http
      scheme: bearer
      bearerFormat: '{$request.body#sinkCredential.credentialType}'
  headers:
    x-correlator:
      description: Correlation id for the different services.
      schema:
        $ref: "#/components/schemas/XCorrelator"
  parameters:
    x-correlator:
      name: x-correlator
      in: header
      description: Correlation id for the different services.
      schema:
        $ref: "#/components/schemas/XCorrelator"
  schemas:
    XCorrelator:
      type: string
      pattern: ^[a-zA-Z0-9-_:;.\/<>{}]{0,256}$
      example: "b4333c46-49c0-4f62-80d7-f0ef930f1c46"
    PopulationDensityRequest:
      type: object
      description: >-
        Request object for retrieving population density data in a
        specified area.
        **NOTE**: The difference between `startTime` and `endTime` cannot be greater than 7 days.
      properties:
        area:
          $ref: '#/components/schemas/Area'
        startTime:
          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
          example: "2023-07-03T12:27:08.312Z"
        endTime:
          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 endTime allowed is 3 months from the time of the request.
          example: "2023-07-03T12:27:08.312Z"
        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: uri
          description: The address where the API response will be asynchronously delivered, using the HTTP protocol.
          pattern: ^https:\/\/.+$
          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
        - startTime
        - endTime
    Area:
      description: Base schema for all areas
      type: object
      properties:
        areaType:
          $ref: "#/components/schemas/AreaType"
      required:
        - areaType
      discriminator:
        propertyName: areaType
        mapping:
          POLYGON: "#/components/schemas/Polygon"
    AreaType:
      type: string
      description: |
        Type of this area.
        POLYGON - The area is defined as a polygon.
      enum:
        - POLYGON
    Polygon:
      description: Polygonal area. The Polygon should be a simple polygon, i.e. should not intersect itself.
      allOf:
        - $ref: "#/components/schemas/Area"
        - type: object
          required:
            - boundary
          properties:
            boundary:
              $ref: "#/components/schemas/PointList"
    PointList:
      description: List of points defining a polygon
      type: array
      items:
        $ref: "#/components/schemas/Point"
      minItems: 3
      maxItems: 15
    Point:
      type: object
      description: Coordinates (latitude, longitude) defining a location in a map
      required:
        - latitude
        - longitude
      properties:
        latitude:
          $ref: "#/components/schemas/Latitude"
        longitude:
          $ref: "#/components/schemas/Longitude"
      example:
        latitude: 50.735851
        longitude: 7.10066
    Latitude:
      description: Latitude component of a location
      type: number
      format: double
      minimum: -90
      maximum: 90
    Longitude:
      description: Longitude component of location
      type: number
      format: double
      minimum: -180
      maximum: 180
    SinkCredential:
      type: object
      properties:
        credentialType:
          type: string
          enum:
            - PLAIN
            - ACCESSTOKEN
            - REFRESHTOKEN
          description: |
            The type of the credential.
            Note: Type of the credential - MUST be set to ACCESSTOKEN for now
      discriminator:
        propertyName: credentialType
        mapping:
          PLAIN: '#/components/schemas/PlainCredential'
          ACCESSTOKEN: '#/components/schemas/AccessTokenCredential'
          REFRESHTOKEN: '#/components/schemas/RefreshTokenCredential'
      required:
        - credentialType
    PlainCredential:
      type: object
      description: A plain credential as a combination of an identifier and a secret.
      allOf:
        - $ref: '#/components/schemas/SinkCredential'
        - type: object
          required:
            - identifier
            - secret
          properties:
            identifier:
              description: The identifier might be an account or username.
              type: string
            secret:
              description: The secret might be a password or passphrase.
              type: string
    AccessTokenCredential:
      type: object
      description: An access token credential.
      allOf:
        - $ref: '#/components/schemas/SinkCredential'
        - type: object
          properties:
            accessToken:
              description: REQUIRED. An access token is a previously acquired token granting access to the target resource.
              type: string
            accessTokenExpiresUtc:
              type: string
              format: date-time
              description: |
                REQUIRED. An absolute (UTC) timestamp at which the token shall be considered expired.
                If the access token is a JWT and registered "exp" (Expiration Time) claim is present, the two expiry times should match.
                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: "2023-07-03T12:27:08.312Z"
            accessTokenType:
              description: REQUIRED. Type of the access token (See [OAuth 2.0](https://tools.ietf.org/html/rfc6749#section-7.1)). For the current version of the API the type MUST be set to `Bearer`.
              type: string
              enum:
                - bearer
          required:
            - accessToken
            - accessTokenExpiresUtc
            - accessTokenType
    RefreshTokenCredential:
      type: object
      description: An access token credential with a refresh token.
      allOf:
        - $ref: '#/components/schemas/SinkCredential'
        - type: object
          properties:
            accessToken:
              description: REQUIRED. An access token is a previously acquired token granting access to the target resource.
              type: string
            accessTokenExpiresUtc:
              type: string
              format: date-time
              description: |
                REQUIRED. An absolute (UTC) timestamp at which the token shall be considered expired.
                If the access token is a JWT and registered "exp" (Expiration Time) claim is present, the two expiry times should match.
                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: "2023-07-03T12:27:08.312Z"
            accessTokenType:
              description: REQUIRED. Type of the access token (See [OAuth 2.0](https://tools.ietf.org/html/rfc6749#section-7.1)).
              type: string
              enum:
                - bearer
            refreshToken:
              description: REQUIRED. An refresh token credential used to acquire access tokens.
              type: string
            refreshTokenEndpoint:
              type: string
              format: uri
              description: REQUIRED. A URL at which the refresh token can be traded for an access token.
      required:
        - accessToken
        - accessTokenExpiresUtc
        - accessTokenType
        - refreshToken
        - refreshTokenEndpoint
    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.
             The request startTime or the request endTime have to be fully covered by the intervals.
             For example, if the intervals are 1-hour long and the input date range were [2024-01-03T11:25:00Z
             to 2024-01-03T12:45:00Z] it would contain 2 intervals (Interval from 2024-01-03T11:00:00Z
             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'
        statusInfo:
          type: string
          description: Information about the status, mandatory when property `status` is `OPERATION_NOT_COMPLETED` for adding extra information about the error.
          example: Some error happened during the processing of the request
      required:
        - timedPopulationDensityData
        - status
    AcceptedAsyncResponse:
      type: object
      properties:
        operationId:
          $ref: '#/components/schemas/OperationId'
      required:
        - operationId
    PopulationDensityAsyncResponse:
      allOf:
        - $ref: '#/components/schemas/PopulationDensityResponse'
        - type: object
          properties:
            operationId:
              $ref: '#/components/schemas/OperationId'
          required:
            - operationId
    OperationId:
      type: string
      description: The unique identifier of the asynchronous operation that is returned when the operation is initiated.
    ResponseStatus:
      type: string
      description: >-
        Represents the state of the response for the input polygon defined in the request, the possible values are:
          - `SUPPORTED_AREA`: The whole request area is supported. Population density data for the entire requested area is returned.
          - `PART_OF_AREA_NOT_SUPPORTED`: Part of the requested area is outside the MNOs coverage area, the cells outside the coverage
          area will have property `dataType` with value `NO_DATA`.
          - `AREA_NOT_SUPPORTED`: The whole requested area is outside the MNOs coverage area. No data will be returned.
          - `OPERATION_NOT_COMPLETED`: An error happened during asynchronous processing of the request. This status will only be returned
          in case the asynchronous API behaviour is used.
      enum:
        - SUPPORTED_AREA
        - PART_OF_AREA_NOT_SUPPORTED
        - AREA_NOT_SUPPORTED
        - OPERATION_NOT_COMPLETED
    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)
          example: "2023-07-03T10:00:00Z"
        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: "2023-07-03T11: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
    CellPopulationDensityData:
      type: object
      description: >-
        Population density data of a cell in a concrete time range. 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:
        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
        dataType:
          type: string
          enum:
            - NO_DATA
            - LOW_DENSITY
            - DENSITY_ESTIMATION
      required:
        - geohash
        - dataType
      discriminator:
        propertyName: dataType
        mapping:
          NO_DATA: '#/components/schemas/NoData'
          LOW_DENSITY: '#/components/schemas/LowDensity'
          DENSITY_ESTIMATION: '#/components/schemas/DensityEstimation'
    NoData:
      allOf:
        - $ref: '#/components/schemas/CellPopulationDensityData'
    LowDensity:
      allOf:
        - $ref: '#/components/schemas/CellPopulationDensityData'
    DensityEstimation:
      allOf:
        - $ref: '#/components/schemas/CellPopulationDensityData'
        - type: object
          properties:
            maxPplDensity:
              type: integer
              description: Maximum people/km2 estimated for the defined area.
            minPplDensity:
              type: integer
              description: Minimum people/km2 estimated for the defined area.
            pplDensity:
              type: integer
              description: people/km2 estimation for the defined area.
          required:
            - maxPplDensity
            - minPplDensity
            - pplDensity
    ErrorInfo:
      type: object
      required:
        - status
        - code
        - message
      properties:
        status:
          type: integer
          description: HTTP response status code
        code:
          type: string
          description: A human-readable code to describe the error
        message:
          type: string
          description: A human-readable description of what the event represents
  responses:
    RetrieveLocationBadRequest400:
      description: >-
        Problem with the client request. In addition to generic scenarios of
        `INVALID_ARGUMENT`, `INVALID_CREDENTIAL`, `INVALID_TOKEN`, another scenarios may exist:
          - 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")
          - Indicated `startTime` is greater than the maximum allowed ("code": "POPULATION_DENSITY_DATA.MAX_STARTTIME_EXCEEDED", "message": "Indicated startTime is greater than the maximum allowed")
          - Indicated `startTime` is earlier than the minimum allowed ("code": "POPULATION_DENSITY_DATA.MIN_STARTTIME_EXCEEDED", "message": "Indicated startTime is earlier than the minimum allowed")
          - Indicated `endTime` is earlier than the `startTime` ("code": "POPULATION_DENSITY_DATA.INVALID_END_TIME", "message": "Indicated endTime is earlier than the startTime")
          - Indicated time period is partially in the past and partially in the future ("code": "POPULATION_DENSITY_DATA.INVALID_TIME_PERIOD", "message": "time period is partially in the past and partially in the future")
          - Indicated time period is greater than the maximum allowed (More than maximum hours between startTime and endTime) ("code": "POPULATION_DENSITY_DATA.MAX_TIME_PERIOD_EXCEEDED", "message": "Indicated time period is greater than the maximum allowed (More than maximum hours between startTime and endTime)")
      headers:
        x-correlator:
          $ref: '#/components/headers/x-correlator'
      content:
        application/json:
          schema:
            allOf:
              - $ref: "#/components/schemas/ErrorInfo"
              - type: object
                properties:
                  status:
                    enum:
                      - 400
                  code:
                    enum:
                      - INVALID_ARGUMENT
                      - INVALID_CREDENTIAL
                      - INVALID_TOKEN
                      - INVALID_SINK
                      - POPULATION_DENSITY_DATA.INVALID_AREA
                      - POPULATION_DENSITY_DATA.MAX_STARTTIME_EXCEEDED
                      - POPULATION_DENSITY_DATA.MIN_STARTTIME_EXCEEDED
                      - POPULATION

# --- truncated at 32 KB (47 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/camara-project/refs/heads/main/openapi/population-density-data-openapi.yml