# Map Widget
## Overview
The Datacake Dashboard Editor features a widget to show one or many positions, including the option to show historical routes and interactivity.
  
## Working with Maps
In order to start with a map widget, you need to add it to a dashboard. The map widget works like mostly all of the widgets on both device and workspace dashboards.
### Placing a Map
Bring your dashboard editor into edit mode and add a new widget. This will open up the widget picker and in here you select the "Map" widget type.
This will add the widget to the dashboard and it will open up the widget editor.
### Geolocation Data & Device Location role
Map Widgets only support database fields of the type "Geolocation". Most of your devices do have a location field available. If you want to learn more about geolocation data types please head over to the database section of this documentation.
It is necessary that you set the role of that Geolocation field as Device Location. For that, go to your device's configuration. Under fields select Edit Field and set the Semantic to Location.
## Adding Data
The location data from your devices that posses a geolocation field will be automatically fed to the map widget. However, if you want to filter which devices get to be shown on a map, you can use tags to select the devices to be shown.
### Any tag or All tags
The option "Any tag" represents an OR function, which means that the map widget will display all devices that have any of the selected tags picked from the drop-down-list above.
The option All tags performs an AND function, which means the map will display the devices that have all tags selected on the drop-down-list.
***
## Markers
The **Markers** tab in the updated **Map Widget** allows you to control what information appears on each device marker displayed on the map. This helps users quickly identify device status, sensor readings, or key operational values at a glance.
***
### **Marker Value**
The **Marker Value** setting determines *which field from your device* is shown directly on the map marker. This value is pulled from the Device Fields Configuration and can be any field you have semantically defined.
#### **What it Displays**
You can choose from any of the following semantic field types:
* **Device Signal**\
Shows the device’s current connection or RSSI/signal strength value.
* **Device Battery**\
Displays the battery level of the device (percentage or voltage, depending on device configuration).
* **Primary Field**\
The field you have designated as the **Primary Value** in your device’s field configuration.\
This is typically the most important sensor reading (e.g., temperature, tank level, position accuracy).
* **Secondary Field**\
The field you set as the **Secondary Value**.\
This might be an additional reading that complements the primary data (e.g., humidity, secondary sensor metrics).
You may edit these values by navigating to your device --> Configuration tab --> Field settings.
#### **Marker Mode**
In **Marker Mode**, each device appears on the map as an individual marker. This mode is ideal when you want to:
* Display device values directly on the map
* See detailed information per device
* Use color or gradients to highlight device states
* Show or hide device names
* Cluster or separate markers
Marker values (e.g., signal, battery, primary/secondary fields) can be configured under the **Markers** section.
#### **Heatmap Mode**
Switching to **Heatmap Mode** changes the visualization from individual markers to a density-based heatmap. This is useful when:
* A large number of devices overlap geographically
* You want to identify hotspots of activity or presence
* Individual device values are less important than spatial distribution
Heatmap mode emphasizes **density**, not per-device metadata.
## **Marker Customization Options**
Below the Map Mode dropdown are several toggles that allow you to tailor how device markers appear.
**Show Device Name**
**Enabling this toggle displays each device's name next to its marker** on the map.
Use this when:
* Devices are sparsely distributed
* Identification of specific devices is important
* You prefer human-readable labels instead of numeric or sensor-based values
Turn it off to reduce visual clutter when many devices overlap.
***
#### **Disable Clustering**
By default, markers that appear close together are grouped into a **cluster bubble**.\
**Enabling “Disable Clustering” forces each device to appear individually**, even when tightly grouped.
Useful for:
* Precise spatial inspection
* Debugging device position accuracy
* Maps with small device counts
Not recommended for dense deployments due to readability issues.
***
#### **Color Markers Based on Device Values**
This option colors each marker based on the **Marker Value** you have selected (e.g., temperature, battery, signal).
What it does:
* Applies a color scale (e.g., low → high)
* Gives quick visual insight into device status
* Useful for dashboards focused on trends or anomalies
If your marker value is a semantic field like **battery** or **signal**, colorization becomes especially meaningful.
***
#### **Use Value-Based Text Colors**
When enabled, the **text inside the marker (the value)** changes color based on the selected value scale.
This is helpful when:
* You want dual visibility: colored marker + colored text
* Markers are small, and text color helps differentiate state
Works best when used together with colorized markers.
***
#### **Use Gradient Color Transitions**
This toggle enables smooth color transitions instead of fixed color blocks.
#### Benefits:
* More visually appealing data gradient
* Easier to distinguish subtle differences
* Ideal for metrics with wide numeric ranges (e.g., temperature, CO₂ levels)
Gradient transitions apply to marker color when **Color Markers Based on Device Values** is active.
#### **Marker Size**
Select the default marker size (Small–X-Large). This setting is used when dynamic sizing is disabled.
***
#### **Use Dynamic Sizing**
Enables automatic marker size scaling based on the selected **Marker Value**.
* **Dynamic Sizing Start** – The smallest marker size in the scale
* **Dynamic Sizing End** – The largest marker size in the scale
Marker sizes adjust proportionally according to the device’s value.
***
#### **Marker Transparency**
Controls how opaque the markers appear on the map.\
Lower percentages make markers solid; higher percentages increase transparency.
***
#### **Enable Marker Blending**
When enabled, overlapping markers visually blend together. This makes dense areas easier to interpret.
***
#### **Display On Color**
Sets the color (and optional text label) for markers when they represent an **active/true/on** state.
#### **Display Off Color**
Sets the color (and optional text label) for markers when they represent an **inactive/false/off** state.
***
## **Map Tab**
The **Map** tab controls the starting position and visual style of the map displayed in your widget.
***
### **Manual Start Location**
When enabled, you can manually set the initial center position and zoom level of the map.\
The widget will always load using this defined starting view, regardless of device locations.
When disabled, the map automatically adjusts to fit all displayed devices.
***
### **Map Style**
Choose the visual style for the map background. Available styles include:
* **Light** – Clean, bright map with minimal contrast
* **Dark** – Dark-themed map ideal for dashboards with darker UI
* **Streets** – Detailed street-level mapping
* **Outdoor** – Terrain-focused style suitable for environmental or field deployments
* **Satellite** – High-resolution satellite imagery
* **Basic** – Simplified map with essential geographic outlines
Selecting a style updates the appearance immediately in the preview at the top.
***
## Appearance
The Appearance section allows you to control behaviour and override default settings such as colours or set a different icon.
***
### Show Device Details on Public Dashboard
Tint Color
Colorises the widget itself.
### **Show Device Details on Public Dashboard**
When enabled, device details (such as name and values) will be visible to anyone viewing a **public** dashboard.\
Disable this option if you want to keep device information private.
***
### **Hide Background**
Removes the widget’s background panel, allowing the map to blend with the dashboard behind it.\
Useful when creating clean or minimal dashboard layouts.
***
### **Show Filtering Panel**
Displays a filter panel at the top of the widget, allowing users to filter the devices shown on the map (e.g., by tags).\
Turn this off if you prefer a minimal, uncluttered widget.
### Full Height Maps
Sometimes you just want to have a single map on a dashboard, and you may want to display it in fullscreen on a wide variety of screen sizes.
However, since our dashboard designer is grid-based, this is not directly possible, as the grids represent an absolute height. Even if you place and scale the widget on the grid in a way that it fully extends to the bottom of your screen, it won't do that on a different screen.
To work around this we have added an option to the map widget that allows you to have the map widget automatically scale to the bottom of the browser window.
In the Appearance section on the map widget settings, you can find an option called "Use full screen height".
After enabling this option and exiting the edit mode of the dashboard editor, the map widget will autoscale to the bottom of the available screen size and/or browser window.
#### Placing additional Widgets
{% hint style="info" %}
You just have to make sure that no other widget is below the map widget. They would stay in their position and be overdrawn by the automatically scaling map widget.
{% endhint %}
Placing Widgets above, left, or right next to the map widget is no problem.
#### Creating a Heatmap
You now have the ability to create a heatmap directly from the Map widget and colour it based on the conditions of your sensors. Below is a tutorial on how to achieve this:
{% embed url="" %}
### Sidebar Dashboards
When you click on a device on a map, the so-called sidebar menu shows on the right side of the browser window.
#### Editing Sidebar Dashboards
For the display of the sidebar dashboard, we use the mobile dashboard layout of a device. This means that you can create or customize the Sidebar Dashboard yourself.
To do this, you have to activate the edit mode of the dashboard in your device and activate the mobile layout.
#### Sidebar Dashboards on Public Dashboard
If you share your global workspace dashboards with others and you want to use the sidebar dashboard feature, you have to enable this first.
To do so, please access the "Appearance" view using the tab bar on the widget editor and enable the option "**Show Device Details on Public Dashboard**" just as shown in the following screenshot.
## Historical Data
**Only** the map widget on your **Device's dashboard** allows you to show historical geolocation data in the form of "routes". You can enable this setting in the map widget editor, under Timeframe. This will unfold a time frame picker and you only need to select one of the available time frame presets.
### High-Resolution Routes
If you select one of our presets we define the number of data points shown on the map, so for example if you select "Day" as a time frame preset we only show a new data point on the map when 15 minutes have passed to the previous one. This can lead to the fact that we are skipping important route points.
{% hint style="info" %}
To manually override the resolution parameter please first select a time frame preset and additionally click on "custom". This will open up an editor where you can set the resolution down to as low as 1 minute.
{% endhint %}
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.datacake.de/dashboards/widgets/map-widget.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.