Population Density Data

Introduction

The CAMARA Population Density Data provides population density estimations for a specific area at the current or a future period of time. The estimation considers historical anonymised information of the network connected devices in the requested area.

Limitations

The Playground implementation will return data for all time frames and for all geographical zones with the following limitations:

• the area in the request must not be too big: (max longitude - min longitude) and (max latitude - min latitude) must be smaller than 0.1
• A maximum of 1000 data chunks is retrieved for one API Call (by chunk we mean a 30 minutes estimation on a geohash zone).
• only the synchronized response mechanism is implemented

API Authentication

HTTPS requests to the REST API are protected with 2-Legged OAuth. To learn more about how Orange Developer handles authentication, please refer to our documentation.

In short, you will use your Orange Developer Authorization header as authorization_header for the Basic authentication with Orange Developer.

You get the Authorization header credentials when you register your application on the Orange Developer Console.

curl -X POST \
-H "Authorization: {{ authorization_header }}" \
-d "grant_type=client_credentials" \
https://api.orange.com/openidconnect/playground/v1.0/token

In response, you will get an access_token.

{
  "token_type": "Bearer",
  "access_token": "66AeYJF8eJQ...2SjkFg9LB1LePC",
  "expires_in": 3600
}

API Description

Summary of resources

This API has one resource retrieve. In the response, the Population Density Data are provided by period of time (split of 30 minutes) and by geohash.

A geohash is a system for encoding geographic coordinates (latitude and longitude) into a compact string of letters and digits. It divides the world into a grid and represents each cell in the grid with a unique alphanumeric code. The precision of a geohash increases with its length; longer geohashes correspond to smaller geographic areas. In this implementation we use precision of 7 meaning that the length of the geohash will be 7 characters.

Summary of methods and URL

Population Density Data - Retrieve

Summary of request body parameters

Note: data type & cardinality are available in the API reference

For the area, we expect in the request a polygon. Following information must be provided:

• areaType valued to POLYGON (mandatory)
• a point list with a minimum of 3, maximum of 15, featuring a latitude and a longitude

Example of body request

{
  "area": {
    "areaType": "POLYGON",
    "boundary": [
      {
        "latitude": 41.351099,
        "longitude": 2.129661
      },
      {
        "latitude": 41.353928,
        "longitude": 2.136373
      },
      {
        "latitude": 41.354663,
        "longitude": 2.135839
      },
      {
        "latitude": 41.351921,
        "longitude": 2.128704
      }
    ]
  },
  "startTime": "2025-03-04T11:00:00.000Z",
  "endTime": "2025-03-04T11:39:59.000Z",
  "precision": 7
}

Summary of response parameters

The response from the Population Density Data API contains population density values represented in time intervals for different cells of the requested area. Each element in the timedPopulationDensityData array corresponds to a time interval, containing population density data for the grid cells.

Notes

• The response may include multiple intervals depending on the requested time range.

Response

200 Match successful
Content-Type: application/json

{
  "timedPopulationDensityData": [
    {
      "startTime": "2025-05-07T14:00:00Z",
      "endTime": "2025-05-07T14:30:00Z",
      "cellPopulationDensityData": [
        {
          "dataType": "DENSITY_ESTIMATION",
          "geohash": "u09tun9",
          "maxPplDensity": 120825,
          "minPplDensity": 56213,
          "pplDensity": 63647
        },
        {
          "dataType": "DENSITY_ESTIMATION",
          "geohash": "u09tunc",
          "maxPplDensity": 134575,
          "minPplDensity": 70874,
          "pplDensity": 79007
        },
        {...}
      ]
    },
    {
      "startTime": "2025-05-07T14:30:00Z",
      "endTime": "2025-05-07T15:00:00Z",
      "cellPopulationDensityData": [
        {
          "dataType": "DENSITY_ESTIMATION",
          "geohash": "u09tun9",
          "maxPplDensity": 115611,
          "minPplDensity": 50062,
          "pplDensity": 62496
        },
        {
          "dataType": "DENSITY_ESTIMATION",
          "geohash": "u09tunc",
          "maxPplDensity": 129097,
          "minPplDensity": 56154,
          "pplDensity": 78297
        },
        {...}
      ]
    }
  ],
  "status": "SUPPORTED_AREA"
}

Most frequent errors

• Maximum time period query-able is 7 days - if the requested period exceed an error 400 is send back with code POPULATION_DENSITY_DATA.MAX_TIME_PERIOD_EXCEEDED
• Only precision 7 is managed - if another value is provided an error 422 is send back with code POPULATION_DENSITY_DATA.UNSUPPORTED_PRECISION
• If the end date is earlier than the start date an error 400 is send back with code POPULATION_DENSITY_DATA.INVALID_END_DATE
• If the end date or the start date is missing an error 400 is send back with code POPULATION_DENSITY_DATA.INVALID_ENDTIME or POPULATION_DENSITY_DATA.INVALID_STARTTIME