label: "Label I want for chart visualization"
AcceptsAn identifier for your map layer, plus sub-parameters defining your map layer properties.
map_layer parameter enables you to define a custom map layer that can then be used to plot regional data, such as counties or zip codes, in Looker and create map charts.
When a map layer exists, typically the interactive map visualization is chosen as the default map visualization. The one exception is the U.S. States map, where Looker uses the Static Map Region chart by default because it uses insets for Alaska and Hawaii.
For more information about creating a custom TopoJSON file, see this Community topic.
Looker recommends you keep custom TopoJSON files smaller than 5 MB to avoid overwhelming the user’s browser tab.
Built-in Map Layers
Looker includes several built-in map layers. Before creating your own map layers, check whether you can use one of the built-in map layers:
countries- Accepts full country names, alpha-3 three-letter country codes, and alpha-2 two-letter country codes.
uk_postcode_areas- Accepts UK postcode areas (e.g.
RHfor Redhill, or
us_states- Accepts full state names and two-letter state abbreviations.
us_counties_fips- Works on string fields that are a five-character FIPS county code for a U.S. county. This layer works only on the interactive map.
us_zipcode_tabulation_areas- This layer works on string fields that are a five-character U.S. zipcode. Dimensions of
type: zipcodeautomatically use the
Zip code regions are based on the 2010 zip code tabulation areas (ZCTAs), so this map layer does not include many zipcodes like P.O. boxes that do not map directly to regions.
Specifying a Map Layer
The location of the map can be specified using either the name of file or a URL.
The general syntax for adding a map layer is:
||String||Name of the map as you will refer to it in LookML.|
||String||Location of the map, specified by the name of a JSON file loaded into the project’s Data section. The file must be in TopoJSON format and have a
||String||The URL to a JSON file that defines the geographic extents of each region available in the map layer. This data is used to automatically center the map on the available data for visualization purposes. The JSON file must be a JSON object where the keys are the mapping value of the feature (as specified by
||String||Name of the TopoJSON object that the map layer references. If not specified, the first object will be used.|
||Data format of the region information. Typically people use
||String||Displayed in the chart configuration UI.|
||Number||Maximum zoom level for zooming in the map layer, for visualizations that support zooming.|
||Number||Minimum zoom level for zooming in the map layer, for visualizations that support zooming.|
||Keyword||Preferred geographic projection of the map layer when displayed in a visualization that supports multiple geographic projections. The LookML Editor lists the many available projections when you add a projection parameter.|
||String||Property from the TopoJSON data to plot against. TopoJSON supports arbitrary metadata for each region. By default, the first matching property is used. If there’s a particular metadata property you want to plot against, specify it here.|
||String||Property from the TopoJSON data to use to label the region. This is useful when the mapping value (defined by
||String||Location of the map, specified by a URL that contains your map file.|
When possible, load your map into the project. For example, if your custom map of neighborhoods, called
my_neighborhoods.json, was loaded into the project’s Data section then you can specify it as:
Alternatively, you could specify that a custom
neighborhoods map is hosted elsewhere, such as at
After the map layer is defined (by specifying a file or using the
url parameter) you can
specify that a dimension’s values should be associated with a geographic region on your custom map. In the dimension, use the
map_layer_name parameter to specify the name you used in the
When you query this dimension and open the visualization section, Looker charts the data using the
neighborhoods TopoJSON file, as defined in the
map_layer parameter in your model file.
Things to Know
Static Map (Regions) Charts
Setting Map to Auto in Static Map (Regions) charts relies on having
map_layer specified in the LookML model specifying a map layer. Without that parameter set, users get an error if they select Auto but can still use Looker’s built-in maps.