For the complete DHIS2 documentation index, see llms.txt.

Using the Maps app¶

About the Maps app¶

The Maps app was introduced in release 2.29 as a replacement for the original GIS app, offering a more intuitive and user-friendly interface. Since version 2.34, the mapping engine is based on WebGL technology, capable of showing thousands of features on a map simultaneously.

Note

The Maps app requires WebGL. Visit get.webgl.org to verify that WebGL is working in your browser or to troubleshoot display issues.

With the Maps app, you can overlay multiple layers and choose from different basemaps. Supported layer types include thematic maps, events, tracked entities, facilities, org unit boundaries, and Earth Engine data such as population, elevation, or climate indicators. You can label features, search and filter data, and save or share maps with other users, or download them as an image. Saved maps can be added to dashboards in the Dashboard app. Thematic layers also integrate with the Data Visualizer app, letting you open the same data as a chart.

Note

To use predefined legends in the Maps app, you need to create them first in the Metadata Management app.

Layers panel¶

The layer panel on the left side of the workspace shows an overview of the layers for the current map:

As layers are added, using the (+) Add layer button, they are arranged and managed in this panel.
The basemap card is always shown at the bottom of the panel. See Basemaps for available options.
The small arrow button to the right of the layer panel, at the top, allows the panel to be hidden or shown.

Each layer is represented by a card in the panel. Along the top of the card are a grab handle for reordering layers with the mouse, the layer title, and an arrow to collapse or expand the card. The middle of the card shows the layer legend where applicable. Along the bottom of the card from left to right are:

An edit (pencil) button opens the layer configuration dialog.
An eye symbol toggles the visibility of the layer.
A slider modifies the layer transparency.
A more actions (three dots) button provides additional options, including showing or hiding the data table, downloading the layer data, duplicating the layer, and removing the layer.

Map controls¶

The + and - buttons on the map allow you to zoom in and out of the map respectively. The mouse scroll wheel zoom is continuous, allowing you to fit the map perfectly to your content.
The rotate map button (triangle arrows) allows you to rotate and tilt the map to enhance the view of your data. Press and hold the button (or hold the Control key on your keyboard) while moving your mouse to change the map view. Click the button again to reset the view.
Fullscreen (four arrows) allows you to view the map in fullscreen. To exit fullscreen, click the button again or press the escape key on your keyboard.
Zoom to content (bounded magnifying glass symbol) automatically adjusts the zoom level and map center position to put the data on your map in focus.
Search (magnifying glass symbol) allows searching for and jumping to a location on the map.
The ruler button allows you to measure distances and areas on the map.
Right-click on the map to display the longitude and latitude of that location.

The File button near the top left allows you to open and save maps. See using the maps file menu for more detailed information.
The Download button next to the File button allows you to download the current map as a PNG image.
The Interpretations button at top right opens an interpretations panel on the right side of the workspace. See viewing interpretations for more information.

Create a new map¶

When you open the Maps app, you start with an empty map canvas and the default basemap selected. If a map is already open, start a new one using File > New. You can change the basemap at any time from the basemap card in the layer panel (see Basemaps).

To add a layer, click the (+) Add layer button in the top left. The layer selection dialog opens:

Available layer types are:

Thematic: Visualize data values (indicators or data elements) aggregated by org unit.
Events: Display individual events from event or tracker programs.
Tracked entities: Display tracked entities and their relationships on the map.
Facilities: Display facilities as icons based on their coordinates.
Org units: Display org unit boundaries.

In addition, several layers may be provided by Google Earth Engine (such as population, elevation, or climate indicators) and other external services. Various Google Earth Engine layer sources are available if the Google Earth Engine API key has been set up (see documentation).

Note

The Maps app administrator can:

Select the sources for Google Earth Engine layers available to other users via the Manage available layer sources button.

Add external layer sources in the Maintenance app.

Basemaps¶

A basemap provides the background map on which your data layers are displayed. You can select and configure the basemap from the basemap card at the bottom of the layer panel.

The following basemaps are available by default:

OSM Light: A minimal, light-colored map based on OpenStreetMap data. This is the default basemap.
OSM Dark: A dark-themed map based on OpenStreetMap data. Useful when the colors on your data layers are bright.
OSM Fiord: A muted, blue-toned map based on OpenStreetMap data.
OSM Detailed: Contains more map features and place names.
Sentinel-2 EOX: Cloud-free satellite imagery showing natural-color views of the Earth's surface at 10m resolution.

If a Bing Maps or Azure Maps API key has been configured by a system administrator, four additional basemaps become available from each provider. Both providers offer the same four styles, prefixed with the provider name — for example, Bing Road and Azure Road:

Road: Shows roads, borders and places.
Dark: A dark-themed road map. Useful when the colors on your data layers are bright.
Aerial: Satellite and detailed aerial imagery.
Aerial Labels: Aerial imagery with place name labels.

A Maps app administrator can also add external basemaps via the Maintenance app. These appear in the basemap card alongside the default basemaps.

Basemap layers are represented by a card in the layer panel. The card shows the list of available basemaps with the current one highlighted. Controls at the bottom allow you to toggle the basemap visibility and adjust its transparency.

Note

Bing Maps is being retired. See the Bing Maps Blog for the retirement announcement. For migration to Azure Maps, consult the Bing Maps Migration Overview.

Manage thematic layers¶

Thematic maps represent spatial variation of geographic distributions. They display aggregated data values for a selected data item (such as an indicator or data element), period and org unit level. Org units with coordinates and matching data values will appear on the map.

Note

You must generate the DHIS2 analytics tables to have aggregated data values available.

Thematic layers are represented by layer cards in the layer panel. The middle of the card shows a legend indicating the value ranges displayed on the layer. The more actions (three dots) button includes options to show or hide the data table, download the data, and open the data as a chart in the Data Visualizer app via Open as chart.

Create a thematic layer¶

To create a thematic layer, choose Thematic on the Add layer selection. This opens the Thematic layer configuration dialog.

1. Data¶

Select a data item.
Select a value from the Aggregation type field for the data values to be shown on the map. By default, "By data element" is selected. Alternative values are: Count, Average, Sum, Standard deviation, Variance, Min, Max. See also Aggregation operators.
Only show completed events: Includes only completed events in the aggregation process. This is useful when you want to exclude partial events in indicator calculations. Available for indicators, program indicators and event data items.

2. Period¶

Select the time span over which the thematic data is mapped.

Period display mode: Select how the selected periods will be visualized on the map:
- Single (default): Displays all selected periods as a single combined layer with aggregated data. Required when only one period is selected or when using start–end dates.
- Timeline: Displays multiple periods as an interactive timeline ordered chronologically. Multiple timeline layers can be added to a map (they will all share the same periods).
- Split: Displays multiple periods side by side for comparison. Supports up to 12 periods (including multi-period presets) and can only be combined with other split layers (they will all share the same periods).
After selecting a display mode, choose how to define the periods:
- Choose from presets: Available for all display modes. You can combine one or more relative and fixed periods.
  - Relative period: Select Relative periods, then the Period type (Years, Months, etc.) and choose one or more relative periods, such as This year and Last year or Last 12 months. A default relative period for analysis can be set in the System Settings app.
  - Fixed period: Select Fixed periods, then choose the Period type (Yearly, Monthly, etc.) and choose one or more fixed periods, such as 2024 or January 2025 and February 2025.
- Define start–end dates: Available only when the Single display mode is selected. Specify exact start and end dates. Both dates are inclusive and will be reflected in the outputs.

3. Org units¶

Select the org units you want to include in the layer. You can freely combine specific org units, org unit levels, org unit groups, and relative user org units (User organisation unit, User sub-units, User sub-x2-units). When user org units are selected, the map data will appear according to the assigned org units for each user in the org unit hierarchy.

Tip: Levels and groups act as filters within the org units you select - combining them will show only org units at those levels or in those groups that are descendants of your selected org units.
Use associated geometry: This dropdown will only show if there are any additional geometries available for your org units. This is typically used to show facility catchment areas.

4. Filter¶

Click Add filter and select an available data item to add a new filter to the data set.
- Select a data dimension from the dropdown box. You can reduce the number of dimensions shown by using the search field. Click the name to select a dimension.
- When a dimension is selected you get a second dropdown with dimension items. Check the items you want to include in the filter.
Multiple filters may be added. Click the trash button on the right of the filter to remove it.

5. Style¶

Select either Choropleth or Bubble map.
- A choropleth map assigns a color to each org unit shape according to the data value. This is the recommended technique if the data is normalized (per capita).
- A bubble map shows data values as proportional circles. Use this technique if the data is not normalized (absolute numbers). The circles are placed in the center of each org unit. Set the Low radius and High radius for the proportional circles. The circles will be scaled between low and high radius according to the data value. The radius must be between 0 and 50 pixels.
Labels: Show org unit names and/or values on the layer. Select Name, Name and value, or Value. Font size, weight, style and color can also be modified.
Count org units without coordinates: Org units without map coordinates are counted and shown in a Data quality section of the legend. They also appear in the data table. These org units may or may not have data.
Select the legend type:
- Automatic color legend: A legend is automatically created based on the classification method, number of classes and color scale you select. Set Classification to one of:
  - Equal intervals: Divides the value range into equally-sized intervals, each spanning (highest value − lowest value) ÷ number of classes.
  - Equal counts: Org units are distributed as evenly as possible across classes (also known as quantile classification). Some datasets cannot be evenly partitioned, particularly when values are heavily repeated or the number of distinct values is small.
  - Natural breaks (intervals) and Natural breaks (clusters): Class boundaries are placed at the largest gaps in the data distribution, based on the ckmeans algorithm. Both methods group values similarly; intervals produces contiguous class ranges, while clusters may leave gaps between classes where no values fall.
  - Pretty breaks: Break points are rounded to clean, human-readable numbers. Based on R's pretty algorithm.
  - Logarithmic scale: Uses a logarithmic scale. Values must be positive; zero or negative values are left unclassified.
  - Standard deviation: Classes are defined as multiples of standard deviations from the mean. The number of standard deviations per class depends on the number of classes chosen; values further from the mean are left unclassified.
  Decimal places: Number of decimal places shown in legend labels. Auto lets the app decide based on the data range, or choose a fixed value from 0 to 6 (also available for single color legends).
  
  Isolated class: Define a value range (min–max) with a fixed color and optional label. Org units in that range are shown separately and excluded from automatic classification.
- Predefined color legend: Select from the predefined legends.
- Single color legend: Select the color of the bubbles or circles. Only available for bubble maps.
Include unclassified org units: Org units whose values fall outside all classification ranges are shown with a configurable color and label (default: "Unclassified").
Include org units with no data: Org units with no data value are shown with a configurable color and label (default: "No data").

Note: All legend items and their counts - including No data and Unclassified - only include org units with coordinates.

Note

Most classes use half-open intervals (startValue ≤ value < endValue): a value sitting exactly on a boundary belongs to the upper class, not the one whose label ends there. The exceptions - where the upper bound is inclusive - are the last class, isolated classes, single-value classes, and clusters (natural breaks).

If the exact class a boundary value belongs to matters for your analysis, use Labels to overlay values directly on each feature. If it still matters after that, consider whether a different legend, maybe with more classes or higher decimal precision, is the right tool for the decision you are trying to make.

Click Add layer.

Modify a thematic layer¶

In the layer panel, click the edit (pencil) icon on the thematic layer card.
Modify the settings on any of the tabs as desired.
Click Update layer.

Filter values in a thematic layer¶

Thematic layers have a Show/hide data table option that can be toggled on or off from the thematic layer card.

The data table displays the data associated with the thematic layer. Click the arrow buttons in a column header to sort by that column. Type in the filter fields below each column header to filter the displayed rows.

The name filter field is an effective way to search for individual org units.

For numeric columns, you can filter using comparison operators: >, <, >=, and <=. Use , for OR logic and & for AND logic — for example: 2,>3&<8 matches the value 2 or any value greater than 3 and less than 8.

Note

Data table filters are temporary and are not saved with the map.

Open org unit profile¶

You can open the org unit profile in three ways:

Click an org unit on the map, then click the View profile button in the popup.
Right-click one of the org units on the map, and select View profile from the menu.
Click an org unit row in the data table.

Navigate between org unit hierarchies¶

When there are visible org units on the map, you can easily navigate up and down in the hierarchy without changing the org unit selection.

Right-click one of the org units.
Select Drill up one level or Drill down one level.

The drill down option is disabled if you are on the lowest level or if there are no coordinates available on the level below. Likewise, the drill up option is disabled from the highest level.

Remove a thematic layer¶

To remove a thematic layer from the map, in the layer card to the left, click the more actions (three dots) icon and then click Remove layer.

Manage event layers¶

The event layer displays the geographical location of events recorded in DHIS2 programs. While in thematic layers you can visualize event data aggregated to org unit level, with event layers you can display the individual events or cases when they have their own point or polygon coordinates. Alternative coordinate fields also let you plot events using locations other than the event itself, such as the org unit or enrollment location.

To display aggregated event statistics at the org unit level, use a thematic layer with event data items instead.

Event layers are represented by layer cards in the layer panel. The middle of the card shows a legend indicating the styling of the layer. The more actions (three dots) button includes options to show or hide the data table and to download the data in GeoJSON format.