Knowledge Drop

How to create a TopoJSON file for use in a Custom Map Layer

  • 5 June 2021
  • 5 replies

Userlevel 5
  • Looker Staff
  • 172 replies

Last tested: June 2021

This Help Center article explains how to make a topojson file to use in a map layer in Looker.

Remember: The property_key field is CASE SENSITIVE! A custom map layer may be set up and referenced correctly, but the map may display blank if property_key is case mismatched.

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


This content is subject to limited support.                

5 replies

Userlevel 7
Badge +1

Can you show us what the labels should look like? I can’t get to work them at all

Userlevel 5

Hi @Dawid_Nawrot , I think this article may answer your question? 
If not, I’m happy to run through an example.


For my example, I took one of our sample topojson files, specifically the Irish counties file.

It starts off with several [X, Y] coordinates, followed by several entries which look like this: 

"TYPE_1":"Administrative County",


We need to pick one of the “properties” to act as our “property_key”. You should pick whichever one matches your data.

My sample data has Irish county names in English, like this:


This matches the values I see in the “NAME_1” property. (For this specific entry, it matches the 3rd row, Leitrim.) So, I will enter “NAME_1” as the property_key. In my example, I did this directly in the visualization settings (while pasting the link to the topojson in the “TopoJSON URL” field):


Alternatively, I could have also uploaded the topojson file to my LookML, in which case I would define a map_layer in the LookML that might look something like this: 

map_layer: irish_counties {
file: "ireland-counties.json"
property_key: "NAME_1"


Let me know if that addresses your question!

Userlevel 7
Badge +1

Yes but that’s just the tooltip, not an actual label on the map. I thought that label would actually provide data for the polygon labels

Userlevel 5

I see. Looker doesn’t automatically write any labels on the map from the topojson file. That would be a feature request. I do have some ideas for a workaround though…


Workaround 1: Use “Map” visualization instead of “Static Region”

In my example above, I used the “Static Regions” visulization type. This will show exactly the region drawn in the topojson file, with nothing else. This looks rather sparse and does not include any labels (unless the topojson itself has labels inside it - see Workaround 2). 

Alternatively, if we write the map layer into the LookML model file and use map_layer in order to connect the dimension to the map layer, then we can use the default “map” visualization. The regions from the json file will superimpose on the default map, and if you zoom in then you should see the default labels (which I assume come from Mapbox and OpenStreetMap).


Workaround 2: Write the labels into the JSON file (somehow)

 By default, when exporting from, labels are not included. It looks like there are ways to render labels on exported SVGs, but not for the json file itself. I couldn’t get anything to work here, but someone with more topojson expertise may be able to hack something.

Userlevel 7
Badge +1

I join my maps with the data by a textual reference, which is also a property_key_label. Don’t quite understand what else is needed here