Population Density Data - CAMARA - Orange Trial 0.2

Getting started

• Disclaimer (trial version)
• Introduction
  • Subscribe to the API
  • API Authentication
  • API Description
    • Summary of resources
    • Summary of methods and URL
    • Summary of request body parameters
    • Request mobile equipement status (from msisdn)
      • Request
      • Response
      • Fields description
    • Most frequent errors
• Looking for support ?
• History of document

Disclaimer (trial version)

This CAMARA- Population Density Data - trial API is a limited version of the production-grade CAMARA - Population Density Data API.

It is running with real network data, against a small geographic area and for a defined time zone (see limitations part).

This API could be suspended or upgraded any time without any notice.

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 anonymized information of the network connected devices in the requested area.

Limitations

• The implementation retrieves population density data only from January 1st, 2025 to March 31th,2025 (if other date is used an error message 400 POPULATION_DENSITY_DATA.MAX_STARTDATE_EXCEEDED is send back).

• A maximum of 1000 data chunks is retrieved for one API Call (by chunk we mean a 30 minutes estimation on a geohash zone).

• The geographic zone covered in this trial version is limited to Barcelona area. The area covered is defined with these coordinates:

[ [ 2.094570465035209, 41.281745129447089 ]
 [ 2.27079902501655, 41.432867822653769 ]
 [ 2.198406380044962, 41.477229645498312 ]
 [ 2.016571655638212, 41.382899835383817 ]
[ 2.094570465035209, 41.281745129447089 ] ]

        
        Copied 
      

• in graphical view:

(Hint - MWC area: : [[2.126380,41.354963] [2.133272,41.358484][2.136224,41.354312][2.130281,41.351544]])

Documentation of the API

Subscribe to the API

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

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.

curl -X POST \
-H "Authorization: {{ authorization_header }}" \
-d "grant_type=client_credentials" \
https://api.orange.com/oauth/v3/token

        
        Copied 
      

In response, you will get an access_token.

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

        
        Copied 
      

Go up

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

Go up

Population Density Request Description

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

Response size limitations & sink: We define a 'chunk' as a population density data estimation for a geohash 7 for 30 minutes.

• For a synchronous response (no sink in the request) the response cannot exceed 5000 chunks. If the response exceed 5000 chunks the error POPULATION_DENSITY_DATA.UNSUPPORTED_SYNC_RESPONSE with message "Indicated combination of area, time interval and precision is too big for a sync response" is send back
• For an asynchronous response ( a sink in the request) we limit at 10000 chunks. If the response exceed 5000 chunks the error POPULATION_DENSITY_DATA.UNSUPPORTED_REQUEST with message "Indicated combination of area, time interval and precision is too big" is send back

Exemple of body request

Without callback url

{
  "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
}
}

        
        Copied 
      

With callback url

{
  "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,
  "sink": "https://webhook-muppet.apps.fr01.paas.diod.orange.com/8816a3c6-f482-...-784a8a1d1664"
}
}

        
        Copied 
      

Population Density Response Description

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.

Response Attributes

Notes

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

Example

Looking for support ?

Facing technical issue when using this API ? please contact us

Go up

History of document

Go up