GPS History

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.

GPS History Dashboard

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.

Configuration

At least one device ID or tag must be specified, along with a duration. Optionally, a resolution may be specified.

Duration

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.

GPS History Duration

Resolution

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.

GPS History Side by Side

Block Data

The block data takes two parameters:

GPS History Block Data

  • 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.

Data Attributes

Devices that have a large number of Attributes could potentially cause the block to take a long time to load. To avoid this, you can control what Attributes the device returns along with the location data.

Additional Attributes: Choose how many Attributes are returned from the selected device.

Select Attributes: Choosing specific Attributes to return from the device when “Only return the following additional attributes” is selected under “Additional Attributes”.

GPS History Additional Attributes (Return Some)

State Properties: Choose what state Attributes are returned with the device when “Return all additional attributes from the selected devices” is selected under “Additional Attributes”. 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 undefined.

GPS History Additional Attributes (Return All)

Default Viewport

GPS History Default Viewport

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 lat,lng format.
  • 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 0 points north to the top of the map, and values between -180 and 180 swing the map in either direction.
  • Pitch: Set a default pitch for the map, between 0 (straight overhead) and 60 degrees.

Once a user manually pans or zooms the chart in the dashboard view, the default settings are disregarded until the dashboard is reloaded.

Default Map Style

GPS History Map Style

Optionally, you may choose a particular default map tile set. The two current styles available are Normal and Satellite.

GPS History Map Normal Style

  • Normal is a standard vector map with streets and labels, and changes from a light to a dark style depending on the theme chosen for viewing the dashboard.

GPS History Map Satellite Style

  • 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 remains the same no matter what theme is chosen for the dashboard.

You are be able to toggle the map type from the dashboard view, but the map will always load with the default style chosen here.

You may also include arrows on your history lines to show the direction of movement between your GPS points, as shown in the screenshots above.

Point Display Configuration

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.

Point Display Configuration

Line Decorators

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.

Arrow Decorators

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.

Cluster Points

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.

ClusteringExample

Simple Pin Style Configuration

Simple Pin Style Configuration

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.

Advanced Pin Style Configuration

Advanced Pin Style Configuration

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 @2x or @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.

Popup Style Configuration

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.