In Looker, we can define custom map regions to display geographical data in addition to the built-in map layers available. Let's say we have a table of average ages for three neighborhoods, shown below:

We would like to map Customer Neighborhood to a particular geographic region, so it can be visualized on a map. To accomplish this, we can follow the steps below:

Prepare Region Data

To prepare the region data, we need a data file that contains the geographic shapes of each region and also contains metadata that associates the region with the data in the database.

Looker uses a format called TopoJSON to store this data in a compact way. TopoJSON files can be easily created from many common shapefile formats, or you can draw one yourself with online tools, as detailed in this Community post: Converting Shapefiles to TopoJSON.

In the case of our example, we have already prepared a TopoJSON file that provides this mapping. Each of the regions in the TopoJSON file have a property called neighborhood that matches the values of the Customer Neighborhood field, which is defined in our LookML project as a dimension called neighborhood.

Upload Region Data

To import the region data into Looker, we can drag and drop the TopoJSON file into the project. This data will be committed alongside the LookML code and updated like any other code in a LookML project.

Uploading region data is available in Looker 4.8 and above.

Create the Map Layer

Now that we have the region data in the project, we need to create a map layer in the LookML model.

We can add a definition in the model file using the map_layer parameter:

  map_layer: my_neighborhood_layer {
  file: "neighborhoods.topojson"
  property_key: "neighborhood"
}
  

The file parameter references the name of the file in the project that contains the region data, and the property_key is the property of the dataset we would like to expose within Looker. If you're not sure what the key is, simply omit the property key and Looker will attempt to select the appropriate key.

Pro Tip: You can also use a TopoJSON file that's hosted elsewhere online, by specifying url instead of file in the layer definition:

      map_layer: my_neighborhood_layer {
      url: "https://raw.githubusercontent.com/cooluser/JSON_Stuff/master/Neighborhoods.topoJSON"
      property_key: "neighborhood"
    }
  

Associate the Map Layer with Data

The only thing left to do is associate the dimension neighborhood in the view with the newly-created map_layer by applying the map_layer_name parameter .

   dimension: neighborhood {
  sql: ${TABLE}.neighborhood ;;
  map_layer_name: my_neighborhood_layer
}
  

This tells Looker that the values of this dimension are associated with the property_key exposed by the map layer. It also lets Looker know it's possible to display this data on a map.

Viewing the Map

The queries that use the neighborhood dimension can now be displayed on a map from the Explore page: