Real Time Crowd Management

Documentation
TELCODATA

Real Time Crowd Management API Overview

Monitor the heartbeat of an event, a demonstration or a gathering during a specific time horizon of the activity and react quicker and more efficiently on (un)expected situations.

Real-time data

Collect aggregated real-time information on flows of visitors, with or without profile details.

Local and roaming

The RTCM API allows you insights on visitor flows that consist of national and international people:

  • How many people are in my selected zone during this period?
  • Can I see anomalies in selected area's?
  • How does people density evolve in selected area's?

Only group amounts above 30 persons are being reported.

Detail

Zones are converted into a grid of bins to create more detail. The size of a bin is 100m x 100m.

Try it out for free! Stream data for 1 hour with a time interval of 5 min covering only one predefined zone.

Real Time Crowd Management microsite

From the moment you have a subscription you can use the link below to access the RTCM Microsite. The microsite allows you to define and manage zones and data streams without the need to dive into APIs.

Go to the microsite

How to get started?

How to get started with RTCM

Getting started with RTCM

RTCM, or Real Time Crowd Management, allows the user to define zones of interest to measure the number of people in a certain area within Belgium. This works by looking at the amount of mobile devices connected to specific cell towers/antennas in the given area. A separation between international and national numbers is available in our API.

After you define your zone(s), you can create a stream to get notified every x minutes about a specific zone. A stream expires after the specified time.

Example code

The RTCM Bin viewer is available on the Enabling github as a demonstration/example of how to consume/visualise the data that is provided by this API.

Zones

A zone can be created by providing a name and the wkt of your choice. One way to generate this wkt can be found below. Please note that the RTCM API only accepts POLYGON and POINT objects. In cases where you provide a POINT object, you'll need to specify the radius as well.

Once your create request is made, our API will divide your wkt in so-called 'bins'. These bins are rectangular bounding boxes within the Lambert azimuthal equal-area projection EPSG:3035 that are calculated according to the area of the wkt you requested. The mobile device count is calculated per bin and will be available in your stream(s).

The RTCM API also includes a feature that allows you to request this bin information for your wkt, without the actual creation of a zone. This way you can test and adapt your wkt to get the best result. For more information, please check the API docs.

More information about the bins themselves and the system used in the IDs is provided is available below

Streams

After you create your zone(s), it's time to set up a stream for one of the zones. Several things must be specified to set up your stream:

  • The zone you created before.
  • The interval of the updates being sent.
  • The endpoint type and address where you want to receive these updates. Right now only HTTP is supported, but don't hesitate to contact us if you have a special request.
  • The duration of your stream.

As mentioned earlier, a zone is divided in bins (cells) and will be available in your stream(s). Response payload example:

[
  {
    "binId": "250mE392400N309775",
    "national": 314,
    "international": 21
  },
  {
    "binId": "250mE392375N309750",
    "national": 236,
    "international": 16
  },
  {
    "binId": "250mE392400N309575",
    "national": 103,
    "international": 2
  },
  {
    "binId": "250mE392450N309700",
    "national": 277,
    "international": 21
  },
  ...
]

Disclaimer: The data used has an accuracy at cell level

Well Known Text (WKT)

A wkt (well-known text), is a way to represent vector geometry objects. The RTCM API accepts two types of wkt: POLYGON and POINT. Please make sure that the wkt is provided in the Lambert azimuthal equal-area projection EPSG:3035.

Generating WKT's

Follow the steps below to generate a wkt for an area of interest.

  1. Download QGIS for your OS.
  2. Open QGIS.
  3. Navigate to Plugins > Manage.
  4. Install following plugins: Get WKT and OpenLayersPlugin (for 3.0+ you might have to enable experimental plugins to be able to install this).
  5. Add OpenStreetMap to the Layers Panel following these steps:

Web -> OpenLayers Plugin -> OpenStreetMap -> OpenStreetMap The OpenStreetMap layer will be shown in the Layer Panel. Layer panel

  1. Click EPSG:3857 (bottom right) and search for EPSG:3035, select it and click Apply + OK. Project properties

  2. Add a temporary layer by navigating to: Layer > Create Layer > New Temporary Scratch Layer…

Make sure to select the desired geometry type (only POLYGON and POINT are allowed by EnCo) and select EPSG:3035 as the project. New temporary scratch layer

  1. Make sure the created layer from step 7 is selected in the Layers Panel.
  2. Make sure Toggle Editing is selected and then click Add Feature. Add feature
  3. The following step is different depending on the geometry type chosen in step 7.
  • Point: just left-click on the map on the area you are interested in. A dot will be shown on the map.
  • Polygon: left click on the map to add corners to your polygon. When you're done, just right click (anywhere is fine) and the polygon will be created.
  1. Click on the icon Select Features by area or single click and click on the created point or polygon from step 10. Your selected area should be colored in yellow. Select feature

  2. Click the wkt icon and your POLYGON or POINT wkt will be shown. This wkt can be used for the RTCM API. Point example Polygon example

Bins

The bins are based on an EEA reference grid within the Lambert azimuthal equal-area projection EPSG:3035.

Each bin is a square with a size ranging from 100 meters, up to 100km. The size is automatically chosen depending on the surface area of you wkt, with as ultimate goal that the total number of bins should not exceed 1,000 by much. The table below gives an overview of the relation between the area covered by the request (only the overlap with our coverage area is taken in to account) and the resulting bin size:

Lower area limit Upper area limit Bin size
0 10km2 100m
10km2 62.5 250m
62.5km2 250km2 500m
250km2 262.5km2 750m
262.5km2 1000km2 1km
1000km2 6250km2 2.5km
6250km2 25000km2 5km
25000km2 7.5km

A bin is identified with an ID from which you can also derive the area itself. Let's look at "100mE39412N30758" for example.

  • The first part is the size, in this case the bin size is 100m.
  • Next we find the longitude in EPSG:3035. Note that insignificant zeroes are omitted, so the actual longitude is, 39412 times 100m East = 3941200.
  • And finally the latitude in EPSG:3035 also without the insignificant zeroes. So the actual latitude is 30758 times 100m North = 3075800.

If we take into account that the coordinates in EPSG:3035 are specified in meters, we can even reconstruct the wkt for this bin, it is in fact:

POLYGON((3941200 3075800,3941300 3075800,3941300 3075900,3941200 3075900,3941200 3075800))

When the bin size is 250m, only one 0 can be omitted, so for example "250mE392375N309750" means:

  • Size 250m
  • Longitude = 392375 times 10m East = 3923750
  • Latitude 309750 times 10m North = 3097500.

And in this case we can derive that the wkt should be:

POLYGON((3923750 3097500,3924000 3097500,3924000 3097750,3923750 3097750,3923750 3097500))

Note: You can use the QuickWKT plugin in QGIS described above to visualize these areas. Once it is installed select QuickWKT from the plugin menu and paste your WKT in the dialog (make sure that you are using EPSG:3035 before using the plugin)

RTCM API

The RTCM (Real Time Crowd Management) API allows you to manage your zones and streams.

Base url: https://api.enco.io/rtcm/1.0.0

Header Value Required
Authorization Bearer <access token> Yes
Accept application/json Yes
Content-type application/json Yes

The access_token should be retrieved via the authentication API. See the Authentication page

/zones GET
/zones POST
/zones/info POST
/zones/{name} GET
/zones/{name}    DELETE

/streams GET
/streams POST
/streams/{id} GET
/streams/{id} DELETE

/logs GET

/zones GET

Returns a list of zones defined for your account.

Response payload

[
  {
    "name": {string},
    "wkt": {string},
    "surface": {number},
    "granularity": {integer},
    "bins": [
      {
        "cellcode": {string},
        "wkt": {string}
      }
    ]
  }
]

/zones POST

Define a new zone. Zones are defined using a WKT string, it is required that this WKT string is either a Polygon or a Point. When defining a zone with a point, please use the radius property to set a radius around this point.

Request payload

{
  "name*": {string},
  "wkt*": {string},
  "radius": {integer}
}

ESPG:3035 More information can be found here.

Response payload

{
  "name": {string},
  "wkt": {string},
  "surface": {number},
  "granularity": {integer},
  "bins": [
    {
      "cellcode": {string},
      "wkt": {string}
    }
  ]
}

/zones/info POST

Get information about a new zone without defining it. Use this method to try out how big a zone will be and in how much bins it will be divided.

Request payload

{
  "name*": {string},
  "wkt*": {string},
  "radius": {integer}
}

ESPG:3035 More information can be found here.

Response payload

{
  "name": {string},
  "wkt": {string},
  "surface": {number},
  "granularity": {integer},
  "bins": [
    {
      "cellcode": {string},
      "wkt": {string}
    }
  ]
}

/zones/{name} GET

Get information about a zone with given name.

Response payload

{
  "name": {string},
  "wkt": {string},
  "surface": {number},
  "granularity": {integer},
  "bins": [
    {
      "cellcode": {string},
      "wkt": {string}
    }
  ]
}

/zones/{name} DELETE

Delete a zone with given name.

/streams GET

Get a list of streams defined for your account.

Response payload

[
  {
    "id": {string},
    "zoneName": {string},
    "endpoint": {
      "type": {string} ["HTTP"],
      "address": {string},
      "authorization": {
        "type": {string} ["NONE", "BASIC"],
        "username": {string},
        "password": {string}
      }
    },
    "state": {string} ["ACTIVE", "PENDING", "STOPPED"],
    "interval": {integer} [1, 5],
    "duration": {integer} [1, 3, 6, 12],
    "timeStart": {string:datetime},
    "timeEnd": {string:datetime}
  }
]

/streams POST

Sets up a new stream.

Request payload

{
  "zoneName*": {string},
  "endpoint*": {
    "type*": {string} ["HTTP"],
    "address*": {string},
    "authorization": {
      "type*": {string} ["NONE", "BASIC"],
      "username": {string},
      "password": {string}
    }
  },
  "interval*": {integer} [1, 5],
  "duration*": {integer} [1, 3, 6, 12],
}

Response payload

{
  "id": {string},
  "zoneName": {string},
  "endpoint": {
    "type": {string} ["HTTP"],
    "address": {string},
    "authorization": {
      "type": {string} ["NONE", "BASIC"],
      "username": {string},
      "password": {string}
    }
  },
  "state": {string} ["ACTIVE", "PENDING", "STOPPED"],
  "interval": {integer} [1, 5],
  "duration": {integer} [1, 3, 6, 12],
  "timeStart": {string:datetime},
  "timeEnd": {string:datetime}
}

/streams/{id} GET

Fetch the stream definition with given id.

Response payload

{
  "id": {string},
  "zoneName": {string},
  "endpoint": {
    "type": {string} ["HTTP"],
    "address": {string},
    "authorization": {
      "type": {string} ["NONE", "BASIC"],
      "username": {string},
      "password": {string}
    }
  },
  "state": {string} ["ACTIVE", "PENDING", "STOPPED"],
  "interval": {integer} [1, 5],
  "duration": {integer} [1, 3, 6, 12],
  "timeStart": {string:datetime},
  "timeEnd": {string:datetime}
}

/streams/{id} DELETE

Stops and deletes a stream with given id.

/logs GET

Returns logs for the RTCM API

Parameter Description Type Required
type The type of logs to be retrieved. "stream-error" string
year The year to search in integer yes
month The month to search in integer yes
function Function to execute on the logs. "interval": retrieves all results in the specified interval. "groupByDay": retrieves an overview of the month specified string yes
startTime mandatory with "interval" function datetime no
endTime mandatory with "interval" function datetime no
page Used for paging. You can specify "first", "next", "previous" or "last" page. string no
pageref Used for paging. Identifies where to start the next or previous page. string no
limit Limits the amount of results to be returned integer no

Response payload

[
  {
    "timestamp" : {string:datetime},
    "rtcmMessage" : {string},
    "rtcmStreamId": {integer}
  }
]
  • All rights reserved. © 2019 Proximus|Cookie policy
  • This site was created and is managed in accordance with Belgian law.
  • Proximus API Solutions - powered by ClearMedia NV. Merksemsesteenweg 148, B-2100 Deurne. BE 0831.425.897