A family of styles with many flavours: Introducing Refill, Cinnabar, and Zinc styles for Tangram


At Mapzen we’re interested in radically improving access to open data. Having more open geo data is great and is something we’re working hard on with projects like Who’s On First, Metro Extracts and contributions to OpenStreetMap. But it’s just as important to us that mappers should have easy access to open data so you can focus on creating great products and experiences, and not get stuck wrangling data.

Today we’re announcing 3 beautiful, ready-to-use styles that allow you to integrate Mapzen’s versatile Vector Tiles service and our Tangram graphics engine into your web and mobile mapping projects with just a couple lines of code. Have you wanted to dip your foot into Mapzen’s mapping stack? Now is the time!

Please use and adapt these open source scene files in your own projects. We’re excited to see what you build! Let us know @mapzen :)

A family of styles …

The following styles are all built on the same skeleton of map features (curated by zoom), but each is skinned for a different cartographic goal. Even though they look different, via the power of boolean visibility and color variables they are only a few dozen lines different. You don’t need to be a Tangram styling pro to remix these styles. We’ll blog more about that soon.



The first style is called Refill and has been previewed in some Mapzen projects already like the Who’s On First Spelunker. Refill provides a high contrast, black & white basemap useful for data visualization.

Refill is a continuation of the Toner style Geraldine started at Stamen. With the GL capabilities of Tangram, detailed lines, patterns and building extrusions are further explored and elaborated upon from the previous Toner base-style. Toner was a style created at Stamen as part of their great CityTracking project.



The second style is called Cinnabar and is a High Road influenced evolution of the Traditional style Stamen created for Mapzen’s Open Android app last year. This classic style should be your go-to for general mapping applications.



Rounding out the set is Zinc. Like Refill, this style is designed for data visualization. Mapzen’s Zinc style is comparable to Esri’s light gray Canvas style, Mapbox’s Light style, and CartoDB’s Positron style, created by Stamen. If you like any of those, Mapzen’s Zinc basemap style is for you.

… with many flavours

Mapzen offers each style in three flavours, giving you 9 different styling options. Yummy, time to make some (vector) map sandwiches! Curious about map sandwiches? CartoDB has a more recent post.

  1. Default - Some labels for streets, cities, water bodies, and some big parks with name only (no icons). No business labels. Good for data visualization overlays that need to provide some location context.
  2. More labels - Fuller set of labels, including high contrast icons highlighting OpenStreetMap business listing data.
  3. No labels - Just the lines and polygons, please.

The Matrix – live demos and source code

Developer resources

So how do you actually use this stuff? Tangram styles are called “scenes” and are written in YAML, a human-friendly format that relies on indentation rather than delimiters (and is a superset of JSON). The scene file (e.g.: zinc-style.yaml) requires a vector tile source, not the raster image tiles that you may be used to. To use Mapzen’s vector tile service you must first obtain a free developer API key and update your scene file with that key.

Sign up for a Mapzen Vector Tiles API key

Mapzen Vector Tiles are a free, shared tile service. As such, there are generous limitations on requests to prevent individual users from degrading the overall system performance.

  1. Go to https://mapzen.com/developers.
  2. Sign in with your GitHub account. If you have not done this before, you need to agree to the terms first.
  3. Create a new key for Vector Tiles, and optionally, give it a project name so you can remember the purpose of the key.
  4. Keep the web page open so you can copy the key into your source code later.

Building a Leaflet map using Tangram

Using Tangram and Mapzen’s vector tiles inside the popular Leaflet mapping framework is easy. We’ll make it even easier soon to do this via a Leaflet provider, but in the meantime…

  1. Update your copy of the scene file on line 456 to reference the API key you created in Step 3 in the Sign up section above. url: https://tile.mapzen.com/mapzen/vector/v1/{layers}/{z}/{x}/{y}.{format}?api_key={api_key}
  2. Reference the index-demo.html file in any of the style repos for how to configure Leaflet with Tangram and the scene file (e.g.: zinc-style.yaml).
  3. Looking for a more sophisticated implementation that includes basic search? The main index.html file has a more real world example.
  4. Need help testing your map locally? See the README in each repo.
  5. Wondering where to host your map? Make a public repo on Github (or fork ours!) and enjoy their GitHub Pages to github.io magic dance.

Tangram resources

  1. Procedural Cartography with Tangram Patricio’s presentation notes from JS.Geo meetup last month.
  2. Walkthrough: Make a map with Tangram by Rhonda on Mapzen’s documentation team.

You should be all set, happy mapping! But please let us know at hello@mapzen.com or via Twitter @mapzen if you encounter any funk and we’ll help you get up and running.