The GPS History Block shows the path of GPS data points across one or more devices. The map visualizes the historical path of each device as a connected line, with a start and end bubble.
The map will automatically pan and zoom to display all the available data retrieved for the block’s configuration. However, you are free to pan and zoom the map on your own.
At least one device ID or tag must be specified, along with a duration. Optionally, a resolution may be specified.
To view the current location of your devices, select “Last received data point”. This will show your devices on the map as green pins.
To view your devices’ locations over a given period of time, choose any other value for duration. Your devices will show on the map as red starting point pins and green ending point pins, with paths connecting the two showing how the device traveled over the given duration.
Setting a resolution will return only the last data point per resolution period, omitting the other recorded data. Selecting a resolution is recommended for devices that report a large volume of location data to improve dashboard performance.
The block data takes two parameters:
- Device IDS / Tags is a device query for choosing which devices are displayed on the map.
- Attribute is the device attribute that contains the location data. The attribute must be of type GPS string, and any attribute reported by the selected devices that is not of the GPS string type will not be available to choose. If displaying multiple devices on the map via tags or multiple IDs, each device must provide the same attribute name.
Set the default viewport for the block. You can also interact with the map in the block preview and pass its settings to the block configuration by clicking the “Set” button.
- Center: Automatically center the map to the middle of the points returned by the query, or set a manual position for the chart’s center either as a context variable or in a
- Zoom: Automatically zoom the map to display all points returned by the query, or set a manual zoom level.
- Bearing: Set a default bearing, where
0points north to the top of the map, and values between
180swing the map in either direction.
- Pitch: Set a default pitch for the map, between
0(straight overhead) and
Once a user manually pans or zooms the chart in the dashboard view, the default settings are disregarded until the dashboard is reloaded.
Optionally, you may choose a particular map tile set. The two current styles available are
Satellite. Normal is a standard vector map with streets and labels, and will change from a light to a dark style depending on the theme chosen for viewing the dashboard. Satellite uses satellite imagery to display the map with streets and labels overlaid on top - the satellite style does not have themes for light or dark, and will remain the same no matter what theme is chosen for the dashboard.
You may also include arrows on your history lines to show the direction of movement between your GPS points.
By default, other state attributes available in the advanced pin style and popup configuration return the most recently received value for that attribute at the time of any GPS point. However, you may change this behavior to only provide state attributes that were reported at the same time as the GPS state report. In this case, other attributes that were not reported along with the GPS data will return
Losant allows for customization of the pins for points on the map as well as the popups that appear when clicking on a map pin.
By default, Losant draws lines between data points on the map if you are you are looking at a duration of data other than
Last Received Data Point. You can remove these lines so that only individual data points will be displayed.
Optionally, if line decorators are enabled and you are looking at a duration of data other than
Last Received Data Point, you can enable arrow decorators to show which direction your connected device was moving along the line.
Optionally, if you are using the duration of
Last Received Data Point (and so only one data point appears on the map per device), you can enable point clustering. This will cluster points together into groups depending on your zoom level, and you can click on a cluster to zoom into that cluster.
By default, Losant places a red marker at the oldest (starting) point for a series and a green marker at the most recent (ending) point for a series. You can change the color and the transparency of either pin using the color picker for that pin, and the change will apply to all of the relevant start or end pins on the map.
If you want more control over marker pins, you can select
Advanced. This allows you to provide a string template for each individual point in each series displayed on the map. The string template must resolve to a single URL pointing to an image, and the pin will be rendered using the image’s natural width and height. If the template does not resolve to an image, no marker will be displayed for that point. For SVG images, a width and/or height must be explicitly assigned in the outermost
<svg> element in order to render.
Marker images also support images optimized for retina displays. Any image with
@3x immediately before the file extension will render at half or a third of its original size respectively.
Losant provides a helper function
colorMarker, which can be used to create the same kinds of markers that the
simple configuration uses. The function takes a single argument, which is a hex color string, and returns an image URL for a marker of that color. The default template for the advanced section uses this helper, rendering
a red marker for the starting (oldest) point of a series, and a green marker for the ending (most recent) point of a series.
When using the advanced mode, the following variables are available for you to use in the icon template:
isFirstPoint- True if this is the first (oldest) data point in the series.
isLastPoint- True if this is the last (most recent) data point in the series.
index- Index of the current data point in the series.
deviceName- Name of the device that generated this data point.
deviceId- Id of the device that generated this data point.
deviceTags- The tags (as an object) of the device that generated this data point.
latitude- Latitude of the current data point.
longitude- Longitude of the current data point.
time- Time of the current data point.
data.<attributeName>- Value of given attribute at this data point.
Just like the
Advanced pin configuration, the popup configuration allows you to provide a string template that can
be used for rendering the popup for a point. The popup for a point will only be available if there is a pin for that point, make sure that a pin is rendered for any points
that you want to provide a popup for. Device attribute data is only available in the popup pin when it is reported in the same state as the GPS attribute.
String templates for popups are treated as Markdown, allowing for formatting options such as bold and italic. Using Losant’s built-in Handlebars helpers, it is possible to build quite complex popup templates that include images and links. By default the popup template renders simple text with the device name, timestamp of the point, and lat/lng location of the point. If the template renders to an empty string for a point, no popup will appear when clicking the map pin for that point.
The same variables exposed in the advanced pin style configuration are also available in the popup configuration.