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.
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:
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 send 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.
Note: 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 be displayed on the map with the markers drop-down. Options are:
Dashboard's selected device(s): shows the device(s) selected 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 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 the "on click" 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: Create a zone to join together a group of devices and perform aggregations across the last value of a variable in the devices of the zone. Learn more about zones in this article.
Step 11: Change the general "appearance" of the widget with the below parameters:
Define 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 the "roadmap" layer is selected.
Choose a default zoom value for the map.
Custom style your map widget as desired.
3. Map Actions
Within the settings of the Map widget, 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
The map 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 displayed.
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. 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 in which data is computed (average, minimum, maximum, sum, count, last value).
Span: Configure a time range for the aggregation to be made with the data contained within the defined range.
6. Clustering
When a map has a large number of markers it becomes useful to use clusters to identify groups of markers within a defined boundary based on the distribution or density of markers and the map’s zoom level.
To see how marker clustering works, see the example 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 with your application's needs and requirements. Map widgets allow you to import a custom JSON and change its look accordingly. A good source for Google Maps styles is Snazzy Maps.
Note: Custom style only works in Ubidots paid plans.
Following the below steps you will be able to change your map's style theme:
Step 1: Select roadmap as the layer type.
Step 2: For layer style select custom.
Step 3: Click on "open editor" in the "custom map style" option.
Step 4: Go to Snazzy Maps and choose a visualization.
Step 5: Copy the JS style array.
Step 6: Paste it in the custom style editor and click the "save" button.
Step 7: Finish editing your map widget and click "save".
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.