Skip to content
camara
Get started
API Reference
Populationdensitydata

Retrieves population density information in a specified area

POST/populationdensitydata/retrieve

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.

Header ParametersExpand Collapse
"x-correlator": optional string
Body ParametersJSONExpand Collapse
area: object { areaType }

Base schema for all areas

areaType: "POLYGON"

Type of this area. POLYGON - The area is defined as a polygon.

endTime: string

End date time. It must follow RFC 3339 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.

formatdate-time
startTime: string

Start date time. It must follow RFC 3339 and must have time zone. Recommended format is yyyy-MM-dd’T’HH:mm:ss.SSSZ

formatdate-time
precision: optional number

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” 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.

minimum1
maximum12
sink: optional string

The address where the API response will be asynchronously delivered, using the HTTP protocol.

formaturi
sinkCredential: optional object { credentialType }

A sink credential provides authentication or authorization information necessary to enable delivery of events to a target.

credentialType: "PLAIN" or "ACCESSTOKEN" or "REFRESHTOKEN"

The type of the credential. Note: Type of the credential - MUST be set to ACCESSTOKEN for now

One of the following:
"PLAIN"
"ACCESSTOKEN"
"REFRESHTOKEN"
ReturnsExpand Collapse
status: "SUPPORTED_AREA" or "PART_OF_AREA_NOT_SUPPORTED" or "AREA_NOT_SUPPORTED" or "OPERATION_NOT_COMPLETED"

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.
One of the following:
"SUPPORTED_AREA"
"PART_OF_AREA_NOT_SUPPORTED"
"AREA_NOT_SUPPORTED"
"OPERATION_NOT_COMPLETED"
timedPopulationDensityData: array of object { cellPopulationDensityData, endTime, startTime }

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).

cellPopulationDensityData: array of object { dataType, geohash }

Population density data for the different cells in a concrete time range.

dataType: "NO_DATA" or "LOW_DENSITY" or "DENSITY_ESTIMATION"
One of the following:
"NO_DATA"
"LOW_DENSITY"
"DENSITY_ESTIMATION"
geohash: string

Coordinates of the cell represented as a string using the Geohash system. Encoding a geographic location into a short string. The value length, and thus, the cell granularity, is determined by the request body property precision.

endTime: string

Interval end time. It must follow RFC 3339 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)

formatdate-time
startTime: string

Interval start time. It must follow RFC 3339 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)

formatdate-time
statusInfo: optional string

Information about the status, mandatory when property status is OPERATION_NOT_COMPLETED for adding extra information about the error.

Retrieves population density information in a specified area

curl https://api.example.com/camara/populationdensitydata/retrieve \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $CAMARA_BEARER_TOKEN" \
    -d '{
          "area": {
            "areaType": "POLYGON"
          },
          "endTime": "2024-04-23T14:44:18.165Z",
          "startTime": "2024-04-23T14:44:18.165Z",
          "sink": "https://endpoint.example.com/sink"
        }'
{
  "status": "SUPPORTED_AREA",
  "timedPopulationDensityData": [
    {
      "startTime": "2024-01-03T10:00:00Z",
      "endTime": "2024-01-03T11:00:00Z",
      "cellPopulationDensityData": [
        {
          "geohash": "ezdqemf",
          "dataType": "DENSITY_ESTIMATION",
          "maxPplDensity": 150,
          "minPplDensity": 30,
          "pplDensity": 60
        },
        {
          "geohash": "ezdqemg",
          "dataType": "DENSITY_ESTIMATION",
          "maxPplDensity": 100,
          "minPplDensity": 40,
          "pplDensity": 90
        },
        {
          "geohash": "ezdqemu",
          "dataType": "LOW_DENSITY"
        }
      ]
    },
    {
      "startTime": "2024-01-03T11:00:00Z",
      "endTime": "2024-01-03T12:00:00Z",
      "cellPopulationDensityData": [
        {
          "geohash": "ezdqemf",
          "dataType": "DENSITY_ESTIMATION",
          "maxPplDensity": 100,
          "minPplDensity": 30,
          "pplDensity": 70
        },
        {
          "geohash": "ezdqemg",
          "dataType": "DENSITY_ESTIMATION",
          "maxPplDensity": 200,
          "minPplDensity": 40,
          "pplDensity": 100
        },
        {
          "geohash": "ezdqemu",
          "dataType": "DENSITY_ESTIMATION",
          "maxPplDensity": 200,
          "minPplDensity": 40,
          "pplDensity": 100
        }
      ]
    }
  ]
}
{
  "status": "AREA_NOT_SUPPORTED",
  "timedPopulationDensityData": []
}
{
  "status": "PART_OF_AREA_NOT_SUPPORTED",
  "timedPopulationDensityData": [
    {
      "startTime": "2024-01-03T10:00:00Z",
      "endTime": "2024-01-03T11:00:00Z",
      "cellPopulationDensityData": [
        {
          "geohash": "ezdqemf",
          "dataType": "DENSITY_ESTIMATION",
          "maxPplDensity": 150,
          "minPplDensity": 30,
          "pplDensity": 60
        },
        {
          "geohash": "ezdqemg",
          "dataType": "DENSITY_ESTIMATION",
          "maxPplDensity": 100,
          "minPplDensity": 40,
          "pplDensity": 90
        },
        {
          "geohash": "ezdqemu",
          "dataType": "NO_DATA"
        }
      ]
    },
    {
      "startTime": "2024-01-03T11:00:00Z",
      "endTime": "2024-01-03T12:00:00Z",
      "cellPopulationDensityData": [
        {
          "geohash": "ezdqemf",
          "dataType": "DENSITY_ESTIMATION",
          "maxPplDensity": 100,
          "minPplDensity": 30,
          "pplDensity": 70
        },
        {
          "geohash": "ezdqemg",
          "dataType": "DENSITY_ESTIMATION",
          "maxPplDensity": 200,
          "minPplDensity": 40,
          "pplDensity": 100
        },
        {
          "geohash": "ezdqemu",
          "dataType": "NO_DATA"
        }
      ]
    }
  ]
}
{
  "status": 400,
  "code": "INVALID_ARGUMENT",
  "message": "Invalid input"
}
{
  "status": 400,
  "code": "INVALID_CREDENTIAL",
  "message": "Only Access token is supported"
}
{
  "status": 400,
  "code": "INVALID_TOKEN",
  "message": "Only bearer token is supported"
}
{
  "status": 400,
  "code": "INVALID_SINK",
  "message": "sink not valid for the specified protocol"
}
{
  "status": 400,
  "code": "POPULATION_DENSITY_DATA.INVALID_AREA",
  "message": "The area is not a polygon shape or has an arbitrary complexity"
}
{
  "status": 400,
  "code": "POPULATION_DENSITY_DATA.MAX_STARTTIME_EXCEEDED",
  "message": "Indicated startTime is greater than the maximum allowed"
}
{
  "status": 400,
  "code": "POPULATION_DENSITY_DATA.MIN_STARTTIME_EXCEEDED",
  "message": "Indicated startTime is earlier than the minimum allowed"
}
{
  "status": 400,
  "code": "POPULATION_DENSITY_DATA.INVALID_END_TIME",
  "message": "Indicated endDate is earlier than the startTime"
}
{
  "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 startTime and endTime)"
}
{
  "status": 400,
  "code": "POPULATION_DENSITY_DATA.INVALID_TIME_PERIOD",
  "message": "Indicated time period is partially in the past and partially in the future"
}
{
  "status": 401,
  "code": "UNAUTHENTICATED",
  "message": "Request not authenticated due to missing, invalid, or expired credentials."
}
{
  "status": 403,
  "code": "PERMISSION_DENIED",
  "message": "Client does not have sufficient permissions to perform this action."
}
{
  "status": 404,
  "code": "NOT_FOUND",
  "message": "The specified resource is not found."
}
{
  "status": 422,
  "code": "POPULATION_DENSITY_DATA.UNSUPPORTED_REQUEST",
  "message": "Indicated combination of area, time interval and precision is too big for both synchronous and asynchronous processing"
}
{
  "status": 422,
  "code": "POPULATION_DENSITY_DATA.UNSUPPORTED_PRECISION",
  "message": "Indicated cell precision (Geohash length) is not supported"
}
{
  "status": 422,
  "code": "POPULATION_DENSITY_DATA.UNSUPPORTED_SYNC_RESPONSE",
  "message": "Indicated combination of area, time interval and precision is too big for synchronous processing and asynchronous processing is not enabled"
}
{
  "status": 429,
  "code": "QUOTA_EXCEEDED",
  "message": "Out of resource quota."
}
{
  "status": 429,
  "code": "TOO_MANY_REQUESTS",
  "message": "Rate limit reached."
}
Returns Examples
{
  "status": "SUPPORTED_AREA",
  "timedPopulationDensityData": [
    {
      "startTime": "2024-01-03T10:00:00Z",
      "endTime": "2024-01-03T11:00:00Z",
      "cellPopulationDensityData": [
        {
          "geohash": "ezdqemf",
          "dataType": "DENSITY_ESTIMATION",
          "maxPplDensity": 150,
          "minPplDensity": 30,
          "pplDensity": 60
        },
        {
          "geohash": "ezdqemg",
          "dataType": "DENSITY_ESTIMATION",
          "maxPplDensity": 100,
          "minPplDensity": 40,
          "pplDensity": 90
        },
        {
          "geohash": "ezdqemu",
          "dataType": "LOW_DENSITY"
        }
      ]
    },
    {
      "startTime": "2024-01-03T11:00:00Z",
      "endTime": "2024-01-03T12:00:00Z",
      "cellPopulationDensityData": [
        {
          "geohash": "ezdqemf",
          "dataType": "DENSITY_ESTIMATION",
          "maxPplDensity": 100,
          "minPplDensity": 30,
          "pplDensity": 70
        },
        {
          "geohash": "ezdqemg",
          "dataType": "DENSITY_ESTIMATION",
          "maxPplDensity": 200,
          "minPplDensity": 40,
          "pplDensity": 100
        },
        {
          "geohash": "ezdqemu",
          "dataType": "DENSITY_ESTIMATION",
          "maxPplDensity": 200,
          "minPplDensity": 40,
          "pplDensity": 100
        }
      ]
    }
  ]
}
{
  "status": "AREA_NOT_SUPPORTED",
  "timedPopulationDensityData": []
}
{
  "status": "PART_OF_AREA_NOT_SUPPORTED",
  "timedPopulationDensityData": [
    {
      "startTime": "2024-01-03T10:00:00Z",
      "endTime": "2024-01-03T11:00:00Z",
      "cellPopulationDensityData": [
        {
          "geohash": "ezdqemf",
          "dataType": "DENSITY_ESTIMATION",
          "maxPplDensity": 150,
          "minPplDensity": 30,
          "pplDensity": 60
        },
        {
          "geohash": "ezdqemg",
          "dataType": "DENSITY_ESTIMATION",
          "maxPplDensity": 100,
          "minPplDensity": 40,
          "pplDensity": 90
        },
        {
          "geohash": "ezdqemu",
          "dataType": "NO_DATA"
        }
      ]
    },
    {
      "startTime": "2024-01-03T11:00:00Z",
      "endTime": "2024-01-03T12:00:00Z",
      "cellPopulationDensityData": [
        {
          "geohash": "ezdqemf",
          "dataType": "DENSITY_ESTIMATION",
          "maxPplDensity": 100,
          "minPplDensity": 30,
          "pplDensity": 70
        },
        {
          "geohash": "ezdqemg",
          "dataType": "DENSITY_ESTIMATION",
          "maxPplDensity": 200,
          "minPplDensity": 40,
          "pplDensity": 100
        },
        {
          "geohash": "ezdqemu",
          "dataType": "NO_DATA"
        }
      ]
    }
  ]
}
{
  "status": 400,
  "code": "INVALID_ARGUMENT",
  "message": "Invalid input"
}
{
  "status": 400,
  "code": "INVALID_CREDENTIAL",
  "message": "Only Access token is supported"
}
{
  "status": 400,
  "code": "INVALID_TOKEN",
  "message": "Only bearer token is supported"
}
{
  "status": 400,
  "code": "INVALID_SINK",
  "message": "sink not valid for the specified protocol"
}
{
  "status": 400,
  "code": "POPULATION_DENSITY_DATA.INVALID_AREA",
  "message": "The area is not a polygon shape or has an arbitrary complexity"
}
{
  "status": 400,
  "code": "POPULATION_DENSITY_DATA.MAX_STARTTIME_EXCEEDED",
  "message": "Indicated startTime is greater than the maximum allowed"
}
{
  "status": 400,
  "code": "POPULATION_DENSITY_DATA.MIN_STARTTIME_EXCEEDED",
  "message": "Indicated startTime is earlier than the minimum allowed"
}
{
  "status": 400,
  "code": "POPULATION_DENSITY_DATA.INVALID_END_TIME",
  "message": "Indicated endDate is earlier than the startTime"
}
{
  "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 startTime and endTime)"
}
{
  "status": 400,
  "code": "POPULATION_DENSITY_DATA.INVALID_TIME_PERIOD",
  "message": "Indicated time period is partially in the past and partially in the future"
}
{
  "status": 401,
  "code": "UNAUTHENTICATED",
  "message": "Request not authenticated due to missing, invalid, or expired credentials."
}
{
  "status": 403,
  "code": "PERMISSION_DENIED",
  "message": "Client does not have sufficient permissions to perform this action."
}
{
  "status": 404,
  "code": "NOT_FOUND",
  "message": "The specified resource is not found."
}
{
  "status": 422,
  "code": "POPULATION_DENSITY_DATA.UNSUPPORTED_REQUEST",
  "message": "Indicated combination of area, time interval and precision is too big for both synchronous and asynchronous processing"
}
{
  "status": 422,
  "code": "POPULATION_DENSITY_DATA.UNSUPPORTED_PRECISION",
  "message": "Indicated cell precision (Geohash length) is not supported"
}
{
  "status": 422,
  "code": "POPULATION_DENSITY_DATA.UNSUPPORTED_SYNC_RESPONSE",
  "message": "Indicated combination of area, time interval and precision is too big for synchronous processing and asynchronous processing is not enabled"
}
{
  "status": 429,
  "code": "QUOTA_EXCEEDED",
  "message": "Out of resource quota."
}
{
  "status": 429,
  "code": "TOO_MANY_REQUESTS",
  "message": "Rate limit reached."
}