Adding common map_layers to your instance

It’s now easier than ever to access common world map_layers in Looker. Just drop these bits of code in your model and you’re good to go.

One-time setup

Set Your Mapbox Token

To use any of these map_layers, you’ll need to create a free account on Mapbox.com. Once you’ve created your account, go to your account page to create a token. This free token entitles you to up to 200,000 map loads per month. If you’re using more than that, you’ll need to start paying for a Mapbox account.

Click the button to Create an Access Token, then check the box under Secret Scopes called “TILESETS:READ”. Then click to CREATE TOKEN. Once that’s done, copy the token to your clipboard.

Add your Mapbox Token as a LookML Constant

Next, you’ll need to go to the LookML project where you’re going to be using maps and create a manifest file (if one doesn’t already exist). Create a constant parameter with your Mapbox token like this:

constant: mapbox_api_key {

value: "[YOUR_DEFAULT_PUBLIC_TOKEN_FROM_MAPBOX]"

}

That’s it. Now you’re good to add as many map_layers as you want to this project from the list below. To do so, just add the code block for the map_layer you want to your model file. Then you can reference it by setting the map_layer_name on the dimension in your view that contains the property key.

So, for example, if you were including the Canadian Provinces map_layer, you’d include the code block below in your model file and then do the following in your view:

dimension: english_province_name {

type: string

map_layer_name: canadian_provinces

}

Available map_layers

Canadian Provinces


If you'd like to use the English name of the Canadian provinces as the key (e.g. Quebec, British Columbia, etc.), use the following:

map_layer: canadian_provinces {

format: "vector_tile_region"

url: "https://a.tiles.mapbox.com/v4/looker-maps.oh_canada/{z}/{x}/{y}.mvt?access_token=@{mapbox_api_key}"

feature_key: "provinces"

extents_json_url: "https://rawcdn.githack.com/dwmintz/looker_map_layers/c98a443cfd7dc93191a3f3f6c54059b9a35a9134/canada_provinces.json"

min_zoom_level: 2

max_zoom_level: 10

property_key: "PRENAME"

}

If you’d prefer to use the Standard geographical classification (SGC) code (e.g. 13 for New Brunswick, 48 for Alberta, etc.), use the following:

map_layer: canadian_provinces {

format: "vector_tile_region"

url: "https://a.tiles.mapbox.com/v4/looker-maps.oh_canada/{z}/{x}/{y}.mvt?access_token=@{mapbox_api_key}"

feature_key: "provinces"

extents_json_url: "https://rawcdn.githack.com/dwmintz/looker_map_layers/f5734c99c6ed23ce02e5c368e3774c2a59e82242/canada-provinces-id.json"

min_zoom_level: 2

max_zoom_level: 10

property_key: "PRUID"

}

Canadian FSAs


Forward Sortation Areas (FSAs) are represented by the first three characters of the six-character Canadian ZIP code. There are approximately 1,600 FSAs in Canada. To load a map layer for FSA regions, use the following:

map_layer: canada_fsa {

format: "vector_tile_region"

url: "https://a.tiles.mapbox.com/v4/looker-maps.2ka31zfi/{z}/{x}/{y}.mvt?access_token=@{mapbox_api_key}"

feature_key: "lfsa000b16a_e-as0y69"

extents_json_url: "https://rawcdn.githack.com/dwmintz/looker_map_layers/49062485f99a0742f44857766d6aadff1b4d5f31/canada_fsa.json"

min_zoom_level: 5

max_zoom_level: 11

property_key: "CFSAUID"

}

Canadian FSAs and US ZIPs


Since many companies serve both the US and Canada, it might be helpful to have Canada's Forward Sortation Areas (FSAs) and US ZIP Code Tabulation Areas (ZCTAs) in a single map layer. This map_layer expects either a 3-character FSA or a 5-digit ZCTA in the postal code field.

  

map_layer: us_canada_postal_codes {

format: "vector_tile_region"

url: "https://a.tiles.mapbox.com/v4/looker-maps.8gkhpr0e/{z}/{x}/{y}.mvt?access_token=@{mapbox_api_key}"

feature_key: "us_canada_postal_codesgeojson"

extents_json_url: "https://rawcdn.githack.com/dwmintz/looker_map_layers/9a83b018f3e9db958ccfdf34cc601baec7995448/us_canada_postal_codes.json"

min_zoom_level: 3

max_zoom_level: 12

property_key: "POSTAL_CODE"

}

North American States/Provinces (Canada, Mexico, US)

This layer can be used for mapping the 50+1 US states, the 31+1 Mexican states and the 10 + 3 Canadian provinces in a single layer. The layer expects the full names of the entities, with accents where appropriate. Canadian provinces use their English names.

map_layer: us_canada_postal_codes {

format: "vector_tile_region"

url: "https://a.tiles.mapbox.com/v4/looker-maps.490z8rk0/{z}/{x}/{y}.mvt?access_token=@{mapbox_api_key}"

feature_key: "na_provinces-1sin0g"

extents_json_url: "https://rawcdn.githack.com/dwmintz/looker_map_layers/b072977e16b4586657501a0409bf5e4ecc84bc58/na_provinces_extents.json"

min_zoom_level: 2

max_zoom_level: 8

property_key: "STATE"

}

US ZIP3s


Sometimes full ZIP codes are more granular than you want and the first three digits of the ZIP is more useful. This map_layer expects those three digits as a string.

map_layer: us_zip3 {

format: "vector_tile_region"

url: "https://a.tiles.mapbox.com/v4/looker-maps.6w6t82a6/{z}/{x}/{y}.mvt?access_token=@{mapbox_api_key}"

feature_key: "zip3-60pe24"

extents_json_url: "https://rawcdn.githack.com/dwmintz/looker_map_layers/e8f8cef33b776ad89cbb8772392addb1a29ea60e/zip3_extents.json"

min_zoom_level: 5

max_zoom_level: 11

property_key: "ZIP3"

}

United States Core Based Statistical Areas


If you'd like to use the GEOID to identify CBSAs (e.g. `10180` for Abilene, TX, `18700` for Corvallis, OR), use the following:

map_layer: us_cbsa {

format: "vector_tile_region"

url: "https://a.tiles.mapbox.com/v4/looker-maps.us_cbsa/{z}/{x}/{y}.mvt?access_token=@{mapbox_api_key}"

feature_key: "us_cbsas"

extents_json_url: "https://rawcdn.githack.com/dwmintz/looker_map_layers/ecb8d20baa3fc2c4c77023011f2dfd26ee7a8f02/us_cbsa_geoid"

min_zoom_level: 4

max_zoom_level: 13

property_key: "GEOID"

}

If you’d prefer to use the name of the CBSA (e.g. Augusta-Waterville, ME), use the following:

map_layer: us_cbsa {

format: "vector_tile_region"

url: "https://a.tiles.mapbox.com/v4/looker-maps.us_cbsa/{z}/{x}/{y}.mvt?access_token=@{mapbox_api_key}"

feature_key: "us_cbsas"

extents_json_url: "https://rawcdn.githack.com/dwmintz/looker_map_layers/ecb8d20baa3fc2c4c77023011f2dfd26ee7a8f02/us_cbsa_name"

min_zoom_level: 4

max_zoom_level: 13

property_key: "NAME"

}

United States Public Use Microdata Areas


Use the GEOID to identify PUMAs (e.g. `2500302` for Worcester County (West Central) PUMA).

map_layer: us_pumas {

format: "vector_tile_region"

url: "https://a.tiles.mapbox.com/v4/looker-maps.9qdtc99b/{z}/{x}/{y}.mvt?access_token=@{mapbox_api_key}"

feature_key: "ipums_puma_2010-5ub0py"

extents_json_url: "https://rawcdn.githack.com/dwmintz/looker_map_layers/4a48ef77a012a9be8d9e1df7aa38e783f5f81e82/puma_extents.json"

min_zoom_level: 5

max_zoom_level: 11

property_key: "GEOID"

}

United States Census Tracts (2010)

Census tracts are identified by a 11-digit code called a GEOID, where the first two digits represent the state, the next three digits the county, and the last six digits the tract. This should be stored as a string.

map_layer: census_tract {

format: "vector_tile_region"

url: "https://a.tiles.mapbox.com/v4/dwmintz.3zfb3asw/{z}/{x}/{y}.mvt?access_token=@{mapbox_api_key}"

feature_key: "us_tracts-6w08eq"

extents_json_url: "https://cdn.rawgit.com/dwmintz/census_extents2/396e32db/tract_extents.json"

min_zoom_level: 6

max_zoom_level: 14

property_key: "GEOID"

}

United States Block Groups (2010)

Census block groups are identified by a 13-digit code called a GEOID, where the first two digits represent the state, the next three digits the county, and the next six digits the tract, and the last two digits the block group. This should be stored as a string.

map_layer: block_group {

format: "vector_tile_region"

url: "https://a.tiles.mapbox.com/v4/dwmintz.4mqiv49l/{z}/{x}/{y}.mvt?access_token=@{mapbox_api_key}"

feature_key: "us_block_groups_simple-c0qtbp"

extents_json_url: "https://cdn.rawgit.com/dwmintz/census_extents2/59fa2cd8/bg_extents.json"

min_zoom_level: 5

max_zoom_level: 16

property_key: "GEOID"

}

UK Postal Districts (2012)

UK Post Codes are alphanumeric codes of six-to-eight characters (including a space). The portion before the space is known as the outer code and consists of the postal area (already included as a default map_layer in Looker) and the postal district.

To map postal districts (e.g. SW1W, AB10, etc.) use the following:

map_layer: uk_postal_districts {

format: "vector_tile_region"

url: "https://a.tiles.mapbox.com/v4/looker-maps.63tiis35/{z}/{x}/{y}.mvt?access_token=@{mapbox_api_key}"

feature_key: "PostalDistrict-5b1t0d"

extents_json_url: "https://rawcdn.githack.com/dwmintz/looker_map_layers/daf65f60fd2f58665640418be05167ef25c2fdcc/uk_postal_districts.json"

min_zoom_level: 8

max_zoom_level: 13

property_key: "PostDist"

}

UK Postal Sectors (2012)

UK Post Codes are alphanumeric codes of six-to-eight characters (including a space). The portion before the space is known as the outer code and consists of the postal area (already included as a default map_layer in Looker) and the postal district. The portion after the space is the inner code and consists of the postal sector (the first digit) and the postal unit (the rest).

To map postal sectors (e.g. EC2R 8, BT9 6, etc.) use the following (yes, include the space):

map_layer: uk_postal_sectors {

format: "vector_tile_region"

url: "https://a.tiles.mapbox.com/v4/looker-maps.cq6lxp6d/{z}/{x}/{y}.mvt?access_token=@{mapbox_api_key}"

feature_key: "PostalSector-2trpb4"

extents_json_url: "https://rawcdn.githack.com/dwmintz/looker_map_layers/fc27a696834125e54f7d9a004870d34257016edf/uk_postal_sectors.json"

min_zoom_level: 8

max_zoom_level: 14

property_key: "RMSect"

}

Codes Postaux de France (2015)

French post codes (codes postaux de France) are five-digit strings. This layer includes all the post codes for la Métropole (mainland France, Corsica, and Atlantic/Mediterranean islands). It does not include France d’outre-mer.

Post codes should be formatted as strings (e.g. 75001 for Île de la Cité, 33250 for Pauillac)

map_layer: codes_postaux {

format: "vector_tile_region"

url: "https://a.tiles.mapbox.com/v4/looker-maps.4opqm5ya/{z}/{x}/{y}.mvt?access_token=@{mapbox_api_key}"

feature_key: "codes_postaux_V5_2_2-4z5c9k"

extents_json_url: "https://rawcdn.githack.com/dwmintz/looker_map_layers/db083551a3705d4f3e0b93ce1862f7bc25abf452/codes_postaux_france.json"

min_zoom_level: 3

max_zoom_level: 11

property_key: "ID"

}

Italy Regions and Provinces (2011)

Italy is divided into 20 Regions (e.g. Toscana, Liguria), which are further subdivided into Provinces (e.g. Bergamo, Asti). Each Region in the region map_layer has a code ("property_key: "COD_REG") as well as the name of the region (property_key: "NOME_REG") and you can use whichever you prefer to identify regions. n.b. Region names are ALL CAPS.

map_layer: regioni_italiani {

format: "vector_tile_region"

url: "https://a.tiles.mapbox.com/v4/looker-maps.61hkfosh/{z}/{x}/{y}.mvt?access_token=@{mapbox_api_key}"

feature_key: "reg2011_g"

extents_json_url: "https://rawcdn.githack.com/dwmintz/looker_map_layers/6894c6448fb0721f93e2ce4ce9c30659e6a30c06/regioni_italiani.json"

min_zoom_level: 3

max_zoom_level: 11

property_key: "NOME_REG"

}

Each Province in the province map_layer has a code ("property_key: "COD_PRO") as well as the name of the region (property_key: "NOME_PRO") and you can use whichever you prefer to identify provinces. n.b. Province names are ALL CAPS.

map_layer: province_italiane {

format: "vector_tile_region"

url: "https://a.tiles.mapbox.com/v4/looker-maps.4ocnvk26/{z}/{x}/{y}.mvt?access_token=@{mapbox_api_key}"

feature_key: "province_ditalia"

extents_json_url: "https://rawcdn.githack.com/dwmintz/looker_map_layers/6894c6448fb0721f93e2ce4ce9c30659e6a30c06/province_italiane.json"

min_zoom_level: 3

max_zoom_level: 12

property_key: "NOME_PRO"

}

5 27 6,033
27 REPLIES 27

whisper to prevent bump

Hi
This is exactly what I’m looking for but I’m struggling to get it to work. I’ve added your amazingly helpful code blocks to my lookML and added the map_layer_name to my postcode dimension. I see the default grey map but but there are no additional shapes or lines beyond this and there are no errors in the LookML. As a test I typed a mistake in the url for the codes-postaux to try and force an error but still nothing changed, and no error. So its difficult to pinpoint where the issue is. Any suggestions for debugging? Many thanks!

Hi Helena,

Are you sure you’re using the dynamic map visualization? If you load the Static Maps, those don’t use custom map_layers at all.

Hi
Yes I believe so. I’ve managed to get a map layer working by adding a data file directly to Looker and referencing it using the file parameter in my map_layer definition. But no luck so far using the mapbox url with api code.

And you went through all the preliminary steps to set up a Mapbox account, create a manifest file, and set the LookML constant with the Mapbox API key?

Yes I followed your steps. Is there a way to test the url with the api key outside of Looker? If copy and paste it into a browser I get the error {“message”:“z value is not a number”}.

Yup, the z/y/x values are filled in dynamically to tell Mapbox where on the map you’re focused. Which map_layer are you working on? France Post Codes? I can try to get it to work on my end and share a valid URL without the API key that you can try.

Yes France Post Codes. Thanks so much thats very kind.

Hooray thanks so much that helped me to debug. I’d been a bit too militant in copying and pasting your code blocks. I hadn’t removed the “[” and “]” from around my api key when I copied and pasted “[YOUR_DEFAULT_PUBLIC_TOKEN_FROM_MAPBOX]”. This works beautifully now! I guess lesson learned here is that there is no error in Looker when the url isn’t working, so test it separately. Thank you!

I’m having a similar issue to Helena_Coates but I can’t seem to work my way out of it.

I’ve added the manifest file, added the constant parameter, and pasted the token from my mapbox account (but did not include the brackets).

I’ve pasted the us_canada_postal_codes code block into my LookML model, and replaced the @{mapbox_api_key} snippet with my mapbox token.

I’ve added to my dimension a map layer with a value of: us_canada_postal_codes

But I still just get a grey map. Any hints?

Hello,

I have a follow up question to this thread. I’m trying to set up my own vector tile region of US commuting zones. I have a mapbox account and have successfully used it to access looker-maps. Do you have any tips? Specifically, I’ve created a tileset and style, but I’m not sure how to create the "extents_json_url.

Thank you,
Max

I found this article the explains how to create an extents file for vector tiles: Large custom map_layers with tiles

Sorry for the delay, Max. But yes, that’s exactly where I was going to point you.

Hello @Mintz , is there a way to have to by departement (which are the two first digit of a postal code) ? 
The issue is that I have more than 10k of postal code to put into the map and Looker limits at 5000 points, the only way to merge is to do that by departement but I can’t find a way to do.. 
Do you see a solution ? 

thanks,
Simon

This is exactly what I was looking for! 

Thanks

For anyone working with UK postal codes I found the regex to break the postcode down into districts and sector here: https://gisforthought.com/uk-postcode-breakdown-regex/

Hi! Have anyone worked with a map layer on Swedish counties or municipalities?

Thanks,
Jakob

Dawid
Participant V

You could use this file: https://github.com/deldersveld/topojson/blob/master/countries/sweden/sweden-municipalities.json and incorporate it in Looker and your Data Model.

I have done exactly the same with Spanish Comunidades / Provincias / Municipios,  Comarcas (Catalonia only), and even Neighbourhoods and Districts just for municipality of Barcelona. If you need any help, let me know!

The file has three levels. Second one is county:

25c962a5-1fc3-4a4f-9f69-6bce9d2c17bd.png

and third municipality:

0700c5cd-38f4-4733-9f17-82599d679009.png

That is exactly what I looked for, many thanks @Dawid!! 

@Mintz Both of the UK maps seem to have stopped working for no apparent reason and after no changes to my lookml. I checked in with a looker wizard, we validated the Lookml matches to this post and we tested the API connection multiple times, but all that seems to pull through is a grey map (below).
It might be a problem with the underlying URL? 
Could you look into this?

d167fb04-c994-45ba-9e1e-90243f58b386.png

Dawid
Participant V

Working all right for me:

1588b134-44b5-45f3-8deb-1feb878cd5a1.png

We’re on 21.6.27

Having trouble getting it working if someone could help. 

Trying to get the `map_layer: us_zip3` working. 

  • I have a manifest file in the highest project directory. Replaced the “[token]” with “xxxx” removing the square brackets. 
  • I have the code above in the model file 
    • Replaced `@{mapbox_api_key}` with the access token  xxxxx
      • url: "https://a.tiles.mapbox.com/v4/looker-maps.6w6t82a6/{z}/{x}/{y}.mvt?access_token=@{mapbox_api_key}"
  • Then in the relevant view, I tried adding a dimension

I’ve tried a few combinations like: 

 dimension: us_zip3 {
    type: zipcode
    label: "Zipcode (3 digit)"
    description: "Just the first 3 digits can be useful for visiual charts"
    group_label: "Shipping Address"
    map_layer_name: us_zip3
    sql: LEFT(${TABLE}.zip_code,3) ;;
  }

 dimension: us_zip3 {
    type: string
    label: "Zipcode (3 digit)"
    description: "Just the first 3 digits can be useful for visiual charts"
    group_label: "Shipping Address"
    map_layer_name: us_zip3
  }

 dimension: us_zip3 {
    type: zipcode
    label: "Zipcode (3 digit)"
    description: "Just the first 3 digits can be useful for visiual charts"
    group_label: "Shipping Address"
    map_layer_name: us_zip3
    sql: ${TABLE}.zip_code ;;
  }

Only when I do the last option does the map show values, but it just shows the 5 digit zip values. 

Dawid
Participant V

Show us your data and the map’s preview data as well

what dimension type should I be using for the us_canada_postal_codes map layer? I’m currently doing this:

    dimension: address_fsa {
      label: "Address FSA/Zip Code"
      map_layer_name: us_canada_postal_codes
      description: "The FSA/Zip Code of the match."
      group_label: "Location Details"
      type: zipcode
      sql: ${TABLE}.address_fsa ;;
    }

and it’s only capturing zipcodes and not fsas on the map

Having trouble getting it working if someone could help. 

Trying to get the `map_layer: us_zip3` working. 

  • I have a manifest file in the highest project directory. Replaced the “[token]” with “xxxx” removing the square brackets. 
  • I have the code above in the model file 
    • Replaced `@{mapbox_api_key}` with the access token  xxxxx
      • url: "https://a.tiles.mapbox.com/v4/looker-maps.6w6t82a6/{z}/{x}/{y}.mvt?access_token=@{mapbox_api_key}"
  • Then in the relevant view, I tried adding a dimension

I’ve tried a few combinations like: 

 dimension: us_zip3 {
    type: zipcode
    label: "Zipcode (3 digit)"
    description: "Just the first 3 digits can be useful for visiual charts"
    group_label: "Shipping Address"
    map_layer_name: us_zip3
    sql: LEFT(${TABLE}.zip_code,3) ;;
  }

 dimension: us_zip3 {
    type: string
    label: "Zipcode (3 digit)"
    description: "Just the first 3 digits can be useful for visiual charts"
    group_label: "Shipping Address"
    map_layer_name: us_zip3
  }

 dimension: us_zip3 {
    type: zipcode
    label: "Zipcode (3 digit)"
    description: "Just the first 3 digits can be useful for visiual charts"
    group_label: "Shipping Address"
    map_layer_name: us_zip3
    sql: ${TABLE}.zip_code ;;
  }

Only when I do the last option does the map show values, but it just shows the 5 digit zip values. 

I am facing a similar issue. I initial thought type should be “us_zip3” but no luck! Leads appreciated!

Having trouble getting it working if someone could help. 

Trying to get the `map_layer: us_zip3` working. 

  • I have a manifest file in the highest project directory. Replaced the “[token]” with “xxxx” removing the square brackets. 
  • I have the code above in the model file 
    • Replaced `@{mapbox_api_key}` with the access token  xxxxx
      • url: "https://a.tiles.mapbox.com/v4/looker-maps.6w6t82a6/{z}/{x}/{y}.mvt?access_token=@{mapbox_api_key}"
  • Then in the relevant view, I tried adding a dimension

I’ve tried a few combinations like: 

 dimension: us_zip3 {
    type: zipcode
    label: "Zipcode (3 digit)"
    description: "Just the first 3 digits can be useful for visiual charts"
    group_label: "Shipping Address"
    map_layer_name: us_zip3
    sql: LEFT(${TABLE}.zip_code,3) ;;
  }

 dimension: us_zip3 {
    type: string
    label: "Zipcode (3 digit)"
    description: "Just the first 3 digits can be useful for visiual charts"
    group_label: "Shipping Address"
    map_layer_name: us_zip3
  }

 dimension: us_zip3 {
    type: zipcode
    label: "Zipcode (3 digit)"
    description: "Just the first 3 digits can be useful for visiual charts"
    group_label: "Shipping Address"
    map_layer_name: us_zip3
    sql: ${TABLE}.zip_code ;;
  }

Only when I do the last option does the map show values, but it just shows the 5 digit zip values. 

I am facing a similar issue. I initial thought type should be “us_zip3” but no luck! Leads appreciated!

FYI > Added “map_layer_name: us_zip3” and it worked like a charm.
Refer to this documentation for additional details: https://docs.looker.com/reference/model-params/map_layer

Hi

I followed the instructions, added the manifest and added below to my model file

```
map_layer: canadian_provinces {
  format: "vector_tile_region"
  url: "https://a.tiles.mapbox.com/v4/looker-maps.oh_canada/{z}/{x}/{y}.mvt?access_token=@{mapbox_api_key}"
  feature_key: "provinces"
  extents_json_url: "https://rawcdn.githack.com/dwmintz/looker_map_layers/c98a443cfd7dc93191a3f3f6c54059b9a35a9134/canada_provinces.json"
  min_zoom_level: 2
  max_zoom_level: 10
  property_key: "PRENAME"
}
```

Then added this to my view
```
  dimension: transaction_province {
    type: string
    map_layer_name: canadian_provinces
    group_label: "Transaction Province Name"
    group_item_label: "Transaction Province Name"
    sql: ${transaction_province_full_name} ;;
  }
```

In the dashboard it shows the map but doesn’t show anything on it
 

9c666393-bdd6-4da7-a8a3-8f8542e85988.png
Top Labels in this Space
Top Solution Authors