Showing devices on a Map

The list of devices is provided by the IoT Hub Manager API.

The device telemetry, which includes the (geo)location, is provided by the Device Telemetry API.

Step 1: Get the list of devices

The user selects a device group, which implicitly define the query to use to fetch the list of devices. See the Config UI API for more information.

Request

GET {IoT Hub manager endpoint}/devices?query={query}

Response

Content-Type: application/json; charset=utf-8

{
    Count: ...
    Items: [
        { device }
        { device }
        { device }
        ...
    ]
    "$metadata": {
        $type: DevicesList;1
        $uri: {IoT Hub manager endpoint}/devices?query={query}
    }
}

Note that the content of the response might change over time, for instance when devices are added or removed, and when device properties change. For instance a query like "all devices with firmware 1.2" would return a different list over time. The UI decides whether to cache and reuse the query result, or whether to repeat the query to refresh the response.

Step 2: Get the devices location

For a given period, the UI gets the telemetry from the Device Telemetry API. Each telemetry record includes the location, which is just a value like any other. Some devices might not provide a location, in which case they won't appear in the map. The most recent telemetry message is sufficient to locate the device, so the UI asks only for the last record for each device (using order=desc and grouplimit=1).

The color and size of the device marker on the map might depend on the telemetry values. For example, the size of the marker could depend on the temperature value, or the number of people in a building, etc. To set a device color using it's alert status instead, see "Coloring markers on a Map using alerts data".

Request

Request with GET:

GET {Device Telemetry endpoint}/messages?from={time}&to={time}&order=desc&grouplimit=1&devices=id1,id2,id3,...

Request with POST:

POST {Device Telemetry endpoint}/messages-query
Content-Type: application/json; charset=utf-8

{
    From: {time}
    To: {time}
    Order: desc
    GroupLimit: 1
    Devices: [ id1, id2, id3, ... ]
}

Response

Content-Type: application/json; charset=utf-8

{
    Items: [
        {
            deviceid
            time
            value 1
            value 2
            value N
            $metadata
        },
        {
            deviceid
            time
            value 1
            value 2
            value N
            $metadata
        },
        ...
    ],
    "$metadata": {
        $type: MessagesList;1
        $uri: ...
    }
}