Map visual

A Map visual places the rows of a report on a map, as areas, points, a heatmap, 3D columns or buildings. Use it when where the data sits matters, for example sales by region or stores by city.

Add a map to a report

In the Visualizations panel, pick Map as the visual type.
Drop a field into Location. Each drop adds a field; the well holds up to six, and a seventh is refused. Each field is read through a role: Country, Region (state, province), District (county, municipality), City, Location (text), Latitude, Longitude or Geometry (WKT, GeoJSON).
Check how each field is read. Open the role button on the field and pick a role under Read this field as, or keep Detect from the field name, which reads the field's name (a field named Country, ISO3, Region, City, lat, lng or shape usually finds its role on its own, and anything else is read as free text). What each role expects is on Map locations, matching and pins.
Drop measures into Values. The first measure colours the map, the second sizes the points, and every measure appears in the tooltip and in the chips on the map.
Open Visual > Map to set the Layer and the labels.

Clicking a named place on the map cross-filters the other visuals, using the first named Location field; hold Ctrl or Cmd when you click to add a place to the selection instead of replacing it. Places drawn from Latitude and Longitude or from Geometry do not cross-filter.

Choose a layer and labels

Open Visual > Map. You can change these settings:

Setting	What it does	Default
Layer	Draws the places as Auto, Areas, Points, Heatmap, 3D columns or Buildings. Auto draws areas when most placed rows are areas, such as countries and regions, and points otherwise; Areas falls back to points when no row is an area.	Auto
Snap to building within (m)	How far from a building a point may stand and still take its colour. Shown only with Buildings.	25 (0 to 100)
Show unmatched as points	Keeps points that match no building on the map. Shown only with Buildings.	On
Globe	Shows the world as a globe while zoomed out, and flat once zoomed in. Not available while 3D view is on.	Off
Label language	The language in which the map prints place names. Only languages the map can print are listed.	English
Labels	What each label prints: Auto, Name, Value, Name + value or None.	Auto
Label field	The field that names each place: Automatic, or a Location or Tooltips field.	Automatic
Cluster points	Auto groups the points once a map holds more than 400; On always groups them; Off draws every point. Groups break apart as you zoom in.	Auto

Note

Buildings is listed in Layer once Location holds both a Latitude and a Longitude field, and the hint under the select says what to add until then. At street zoom each point takes the colour of the building it stands in; zoomed out, the map shows points. The zoom rules behind the layer are on Map buildings and the 3D view.

What each Labels mode prints, how a label picks its name, and how callouts, tooltips and the legend read are on Map labels and callouts.

Show the map in 3D

Open Visual > 3D and turn on 3D view to add terrain, hillshade and 3D buildings.
Set Terrain exaggeration to make the terrain taller or flatter.
To stand columns on the data, set Layer to 3D columns in Visual > Map.
Tune the columns in Visual > 3D:

Setting	What it does	Default
3D view	Turns on terrain, hillshade and 3D buildings.	Off
Terrain exaggeration	Terrain height, from 1.0x to 2.5x in steps of 0.1x.	1.5x
Column height	The measure that sets column height. Automatic uses the second measure in Values, or the first when there is only one, and never the measure that colours the map; the columns stand at a uniform height when no measure drives them. Shown with 3D columns.	Automatic
Height scale	Linear or Square root. Shown with 3D columns.	Linear
Max column height	The tallest column, as a share of the map, from 10% to 80%. Shown with 3D columns.	35% of the map

To tilt the map, select the tile and click Interact, then right-drag or Ctrl-drag to tilt and turn. On touch, use two fingers. Click Interact again to stop.
Click Reset view in Visual > 3D to clear the view you left the map in. The button is disabled when no view was saved.
The view you leave is saved with the visual and is used in exports while it still shows the data. Map buildings and the 3D view covers the saving rules and how far a tilt can go.

Move around and read the map

While the map places its rows, the status line reads Placing {n} rows on the map.
Zoom in and Zoom out change the zoom level, and the wheel zooms the map directly (a scroll over a map zooms it, not the page). Show all data returns the map to the view of your data.
When Cluster points groups the points, a group shows how many it holds; click a group to zoom into it.
With more than one measure, the chips on the map pick which measure colours it. The measure that sets point size is marked (point size), and on a 3D columns map, (column height).
The legend shows the colour classes of the active measure, with a size key below. A small tile folds the legend into a one-row strip, and a No data row names the places that hold no value.
Hover a place to read its name and every measure; when several rows share one place, the tooltip says that they are combined.
The map carries the credit for its data sources at all times: © DataMind, © OpenStreetMap, and © Mapterhorn while the 3D view draws terrain. The credit folds to a small mark after a few seconds and unfolds when you click it. Licences opens the Map data and licences dialog; every source is listed on Map data and licences, and Exported maps, credits and notes covers the credit on exported pictures.
On a tilted map, the compass button in the zoom controls turns the map back to north.

Pin places the map could not match

Values that match no place are left out of the map, and the button on the map counts them, for example 3 rows not matched. An editor of the report can pin a value to the place it means; the pin is saved with the visual and the value is listed under Pinned locations in Visual > Map. A visual can carry up to 500 pinned places. Values the map placed by a best guess are listed as {n} to review, and the entry shows Placed as with the guessed name. The full flow is on Map locations, matching and pins.

Coordinates and shapes for your organisation

An administrator decides whether maps may use Latitude and Longitude fields and Geometry fields.

Open Admin > System Configuration, then the Maps tab.
Switch Map coordinates or Map shapes from data on or off, and confirm in the dialog.

Warning

Turning off Map coordinates or Map shapes from data stops every chart that uses those fields from showing its data, until the setting is allowed again. Maps of countries, regions, districts and cities keep working.

Changing these switches needs the System Settings Manager permission, and opening the tab needs System Settings Viewer. See Scheduler, health, maps and connector safety and the Permission reference.

Maps do not look up street addresses. Use place names, or Latitude and Longitude fields for exact positions.

Limits and notes

The Points row under General > Limits starts at 50,000 and goes up to 100,000. With a Geometry field the row reads Shapes and starts at 10,000, up to 25,000. Chart limits lists the row and how to change it.
A First 50,000 rows note appears only when the result was cut short, and it names the limit the run used.
A Geometry result larger than the map's size budget is refused with the message the map's shapes are larger than 32 MB; filter the map to fewer areas or store simpler shapes. A result that carries more detail than the map draws is thinned, and the map notes Shapes simplified.
Buildings colours at most 2,000 buildings and 4,000 points in view, and matches up to 20,000 points to buildings at once; past those limits the map draws plain points and notes why, for example Over 2,000 buildings in view: shown as points.
A map takes one Latitude, one Longitude and one Geometry field, and Latitude and Longitude are used together. A repeated role reports Use one latitude field per map. (the same for Longitude and Geometry), and half a pair reports Add a Longitude field to place the points. or Add a Latitude field to place the points.
If the map cannot read your organisation's map settings, it says Map settings are unavailable right now; try the map again shortly.
When a report export cannot capture a map, the export carries the placeholder Map exports as a picture and a warning.

Questions, answered

My map is empty. Why?

The message None of the locations could be placed on the map. means no row matched a place. Check the role of each Location field; for countries, use a name or an ISO code such as Germany, DE, DEU or 276. A map built on place names also needs the map engine's place data, and when that data cannot be served the map says Location data is unavailable: the map engine does not serve place names and boundaries yet. Maps by latitude and longitude or geometry still work.

Some rows are missing from the map. Why?

Values that match no place are left out of the map, and the button on the map counts those rows, for example 3 rows not matched. An editor of the report can pin a value to the place it means. If instead the map hit its row limit, it adds a First 50,000 rows note.

Can I map addresses without coordinates?

By place name, yes; street addresses are not looked up. A City or Location (text) field places rows from town and city names, and Region (state, province) and District (county, municipality) add detail around them. For an exact point, use Latitude and Longitude fields.

Why can I not use latitude and longitude?

Your organisation has turned Map coordinates off. The map says Latitude and longitude fields are turned off for this organization. Use Country, Region or City fields, or ask an administrator to allow them in the map settings. A run that still carries the fields is refused with latitude/longitude map fields are turned off for this organization; use Country, Region or City fields, or ask an administrator to allow them in the map settings. The same switch covers shapes from a Geometry field, which reads Geometry fields are turned off for this organization. Use Country, Region or District fields, or ask an administrator to allow them in the map settings. An administrator can allow them again under Admin > System Configuration > Maps. Until then, use Country, Region or City fields.

Why is my average or distinct count empty on the map?

Rows that land on one place become one shape or point, and the map combines their values. Sum and Count add the rows together, Min and Max pick one value, and a measure with no summarisation adds too. An Average, a Distinct count or a model measure cannot be combined: the place shows no value for that measure, and the tooltip names it. Text measures appear in the tooltip only.

How do I tilt the map?

Select the tile, click Interact, then right-drag or Ctrl-drag. On touch, use two fingers. Click Interact again to stop. To clear the view you left the map in, click Reset view in Visual > 3D.

Can I show a heatmap?

Yes. Set Layer to Heatmap in Visual > Map. The heat follows the measure that colours the map; with no measure, it counts points.

Why is Buildings not listed in the layer list?

Buildings appears in Layer once Location holds a Latitude and a Longitude field. Until then the hint under the select reads Buildings: add a Latitude and a Longitude field to Location to colour the building each point stands in. If the coordinate fields leave the well while Buildings is chosen, the map draws as Auto, the hint reads Buildings needs a Latitude and a Longitude field in Location; until then the map draws as Auto. and the tile says Buildings need latitude and longitude. Zoomed out, a Buildings map draws points and notes Zoom in to colour buildings. See Map buildings and the 3D view.

Why is Globe greyed out?

Globe is disabled while 3D view is on, with the reason Not with the 3D view: its terrain needs the flat map. Turn the 3D view off to use the globe. Turn 3D view off in Visual > 3D to use it.

How many rows can a map load?

50,000 points by default, up to 100,000. With a Geometry field the limit row is Shapes: 10,000 by default, up to 25,000. Change either under General > Limits; Chart limits covers the row and its maximum. When the map hit the limit, it adds a note such as First 50,000 rows.

Can I change the language of place names?

Yes. Choose a language in Label language under Visual > Map. English is the default, and only languages the map can print are listed; a map saved with a language it cannot print reads as English.

Why did the map stop loading?

An administrator sets the key that maps and the AI features share, under Admin > AI Configuration. The sentence over the map says what is wrong:

Maps are switched off for this installation: the map engine did not accept its platform API key. means the engine refused the key. An administrator checks it in AI configuration.
Maps are not configured: this installation has no platform API key. Set it in Admin → AI Configuration. means no key is set, so no map can load.
The map engine is unavailable. Try again shortly. and The map engine did not answer in time. Try again shortly. are temporary; try again.
The map could not load: the map engine is unreachable. and The locations could not be matched: the place data is unreachable. mean your session could not reach the engine or its place data; try again.
The map engine returned an unreadable style and The map engine publishes no style for this theme yet name a style problem on the engine side; try again, and tell an administrator if it keeps happening.