On this Page
Docs Menu

Go to Model Parameter List


The map_layers parameter enables you to define custom maps that can then be used to plot your data in Looker and create map charts.

You then use the field-level map_layer parameter with a dimension so that you can associate the dimension’s values with a geographic region on your custom map.

See this Discourse article for further information.

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. L for Liverpool, RH for Redhill, or EH for Edinburgh).

  • 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: zipcode automatically use the us_zipcode_tabulation_areas map layer.

    Note: Zipcode regions are based on the 2010 zip code tabulation areas, so this map layer does not include many zipcodes like P.O. boxes that do not map directly to regions.

Adding a Map Layer

The general syntax for adding a map_layer is:

- map_layers: - name: identifier url: "string" - name: another_identifier url: "string" - name: yet_another_identifier file: "string"


  • name denotes the name of the map layer you will use to refer to it in LookML.

  • url, a string, contains a URL that contains your topojson file. We recommend hosting the topojson file in something like a raw Gist for ease of use.

  • file, a string, specifies the name of a JSON file loaded into the project’s Data section. This can be a file with a filetype extension .json, .topojson, or .geojson.


Create a custom Neighborhoods map that is hosted at

- map_layers: - name: neighborhoods url: “”

Create a custom Neighborhoods map called neighborhoods.json that was loaded into the project’s Data section.

- map_layers: - name: neighborhoods file: "neighborhoods.json"

Things to Know

Creating Custom Topojson

For instructions on how to turn a shapefile into a custom topojson on a Mac, see this article.

Still have questions?
Go to Discourse - or - Email Support