Are you interested to know the current position of your devices? For example, logistics companies find it extremely useful to know where their trucks are to estimate package arrival time. Additionally, by tracking a vehicle's movements, alternative routes can be designed to optimize fuel consumption and speed in future endeavors.

Table of Contents:

  1. Defining your Device Location

  2. Creating the Map Widget

  3. Configuring Map action

  4. Configuring Map trace

  5. Metric icon

  6. Clustering

  7. Customizing Map Style Theme

  8. Pro Tips

1. Defining your Device Location

Before creating a Map Widget, Ubidots needs to know where to find the location data from your device(s). Every device has a default property called "Location", which can be found in the left column of the device view:

There are 3 ways to define your device's location:

- Auto: This is the default mode. Ubidots will look for a variable called "gps", "location" or "position" and then see the context of such variable's last value, to find if "lat" and "lng" keys exist. Some examples of a valid last value would be:

{"position": {"value":1, "context":{"lat": "6.5423", "lng": "-70.5783"}}}
{"position":{"lat":6.2442, "lng":-75.5812}}
{"position":{"latitude":6.2442, "longitude":-75.5812}}

In the last two examples, Ubidots will automatically add a value of 1 and make the coordinates part of the value's context to match such format as the first instance.

- Manual: This option allows you to manually type the latitude and longitude coordinates of the device:

This is quite useful for stationary devices, such as weather stations where the exact GPS coordinates are known. You can also use the map displayed at the top device view to manually drag-n-drop a pin into a location.

- Variable-based: Alternatively, if your location variable is not called "gps", "location" or "position", you can also specify it yourself. In the example below, we'll use an "flood_stage" variable, which happens to carry "lat" and "lng" values in its context:

IMPORTANT NOTE: You must send "lat" and "lng" values to the location variable's "context" to let Ubidots read your devices location data. Check this out for additional resources to sending a device's latitude and longitude in the context.

2. Creating the Map Widget

After defining how Ubidots should extract your devices' location, head to the "Data" drop-down in the Navigation bar, then "Dashboards", and select the appropriate dashboard to be working on. Next, follow the below steps to create a map widget:

Step 1:Click on the top-right "+" button.
Step 2: Select the Map widget option.
Step 3: Click on "+ Add marker group" button

If your Dashboard is Dynamic, the option Markers will become available. If not, the option "Select devices" will appear to manually associate the devices to be displayed.

Step 4: Select the device(s) to display on the Map with the Markers drop-down. Options are:
Single device set by dashboard: only shows the selected device in the Dashboard
Device group: displays the devices that belong to the group selected
Device type: displays the devices that belong to the type selected
Dashboard's device list: shows devices based on the Dashboard device list
Selected Devices: displays an option to select specific devices.

Step 5: Select the icon pin:
Pin: standard pin (default option).
Device icon: inherits the device icon.
Location variable icon: inherits the icon of the variable that the system is taking as a reference to find the location coordinates.

Metric: Displays a circle icon that shows data from a selected variable.
None: No markup is displayed.

Step 6: Select Marker color:
Based on value: enable an option called "Custom color", where you need to Add a color logic, then based on a variable's value.
Device color: Inherits the device color.
Location variable color: Inherits the color of the variable that the system is taking as a reference for the location coordinates.

Step 7: Edit "On click action" and "On double click" actions, based on section 3.
Step 8: Edit the map trace option, based on section 4.

Step 9: Enable/disable clustering.

Step 10: Change the general "Appearance" of the widget with the below parameters:
Enter a Name for the widget.
Select a Layer type: Roadmap, Satellite or Hybrid.
Select a Style to theme the map between Light, Dark or Custom (Section 5). Custom option is only available when Roadmap layer is selected.
Choose a default Zoom value for the map.
Custom style your map widget as desired.

3. Map Actions

Within the Map widget settings, there is an option to configure actions when you click or double click the location pin. The following are the available options:

  • Set dashboard device: sets the device in the Dashboard list when the action is performed.

  • Go to device: opens a new tab with the view of the device on which the action is performed.

  • Go to variable: opens a new tab with the view of the variable specified by the user.

  • Go to dashboard: opens a new tab with the specified Dashboard.

  • Display selected variables: shows a list with the last value of the selected variables of the device. Clicking on a variable takes you to the variable view by opening a new tab.

  • Display all variables: Shows a list with the last value of all the variables of the device. Clicking on a variable takes you to the variable view by opening a new tab.

  • Show map trace: displays the trace, as specified in “Map trace settings”.

  • Display address: shows the approximate address based on latitude and longitude coordinates.

  • Display Dashboard: displays a window with the selected dashboard as embedded.

4. Map Trace

Ubidots maps widget allows you to show the trace of a device by configuring the following options:

Aggregation method: Specifies the way the historical data is drawn:

  • Raw: This shows a trace of all the location data of the device. This option can take minutes to respond, and graph.

  • Smooth: Displays a smoothed trace using the Douglas-Peuker algorithm to optimize loading and graphing time.

Span: Configure the time range in which the trace will be display.
Display direction arrows: This shows the direction of movement of the device.
Display on load: Displays the map trace after refreshing the widget or Dashboard. Please enable this option if you want to show the trace, otherwise it will only display the last location point in the time range selected.

5. Metric icon

The map widget allows you to show a metric icon as a marker that displays data from a specified variable, by configuring the following options:

Variable label: the label of the variable you want to display.
Aggregation method: Specifies the way the historical data is drawn.
Span: Configure the time range in which the trace will be display.

6. Clustering

When a map has a large number of markers it becomes useful to user marker clusters to identify groups, or clusters, of markers within a defined grid or boundary based on the distribution or density of markers and the map’s zoom level.

To see how marker clustering works, view the map below.

The number on a cluster indicates how many markers it contains. Notice that as you zoom into any of the cluster locations, the number on the cluster decreases, and you begin to see the individual markers on the map. Zooming out of the map consolidates the markers into clusters again.

7. Customizing Map Style Theme

Sometimes you want the map widget to have a certain look and feel so it complies to your application needs and requirements. Map widget allows you to import custom JSON file to have the Map Widget read it and change the visualization accordingly. A good source for already created visualization JS Style Arrays files is Snazzy Maps.

NOTE: Custom Style only works in Ubidots paid plans.

Following the below steps you will be able to change your Map Widget Style theme:

Step 1: Select Layer type to roadmap.
Step 2: Select Style to custom.
Step 3: Click on "Openeditor" in the "Custom style" option.
Step 4: Go to Snazzy Maps and choose a visualization.
Step 5: Copy the JS Style Array file.
Step 6: Paste it in the Custom style editor.
Step 7: Save it and check out the Map Widget Settings.

8. Pro Tips

Instead of using Google Maps, which is the default maps service used by Ubidots, you might like try other services like Mapbox. If you want to give it a try, check out this tutorial to learn to write your own widgets in Ubidots with the HTML Canvas Widget.

Other users also found helpful:

  1. Events: Was my event triggered? How to check the event's Log

  2. Events: Slack Webhook setup

  3. Ubifunctions: Process/Parse data from 3rd party platforms

Did this answer your question?