When we launched vector tiles back in May 2015 it was essentially a TV pilot episode. The plot, characters and direction were compelling enough to get signed for a full season and we took it to production. Today we’re proud to show you v1.0 of Mapzen’s Vector Tile service!

After 20 months in active development, v1.0 vector tiles is an important milestone and introduces stability to the service API and the underlying Tilezen data model. To get there we had to break a few things. The full story is in the v1.0.0 changelog, summarized below.

What’s evolved since the pilot? Our cast of characters is now at 400 major roles and over 200 minor roles (up from just 200 major roles in v0.1). Tolstoy would be proud! And yes, we have names in Russian, Kannada, and all languages.

Data is organized into 9 layers:

• boundaries, buildings, earth, landuse, places, pois, roads, transit, and water

Like chapters in a book, we reveal data through 18 different map zooms. Zoom 0 fits the world onto your smartphone screen while panning into zoom 18 reveals neighbourhood streets, buildings, and businesses. We’ve spent an insane amount of time orchestrating when each of those 600+ features come in and out of view, how prominent each is, and we’ve sourced quality data for each role.

We’ve obsessed over the details: label boundaries with left and right names, realistic 3D buildings with heights and building parts, points of interest selected for display at low- and mid-zooms to support wayfinding, layering of complex highway interchanges based on overpass and underpass tags, support for advanced road shields, bicycle maps, hiking maps, landuse kind intercuts for roads and buildings, transit line colors, bus routes, transit stations, intermittent streams, coastline boundaries, maritime boundaries, and more.

The focus of v1.0 vector tiles has been four fold:

1. New URL scheme!
2. Smaller file sizes, especially at low- and mid-zooms for better client-side performance.
3. Data model changes for improved consistency of kind values and other properties across all zoom levels, and introduce a new kind_detail property that aggregates across multiple OpenStreetMap source tags for layers like roads.
4. Bug fixes from the v0.10 release focused on outdoor mapping, adding new features such as camp sites and rest areas, and more valid polygon geometries (especially for MVT).

New URL scheme

Mapzen now offers several different types of tiles in vector and raster formats and we combine data from multiple sources. The API endpoints have been updated to reflect this, and emphasize versions and account names.

• GeoJSON: http://tile.mapzen.com/mapzen/vector/v1/all/{z}/{x}/{y}.json?api_key=mapzen-xxxxxxx
• TopoJSON: http://tile.mapzen.com/mapzen/vector/v1/all/{z}/{x}/{y}.topojson?api_key=mapzen-xxxxxxx
• Mapbox Vector Tile: http://tile.mapzen.com/mapzen/vector/v1/all/{z}/{x}/{y}.mvt?api_key=mapzen-xxxxxxx

Legacy tile support

Your existing maps should continue to work, but we recommend upgrading sooner than later. The old production URLs will remain available for the next year but will no longer show the most up-to-date OpenStreetMap data, render new coverage areas on the fly, or return custom layers (only all and buildings layers are archived). Upgrading your maps to v1.0 is straightforward though: here’s the cheatsheet we used internally – let us know if you have any questions!

Smaller file sizes

By removing unnecessary features from low-zooms and merging landuse and buildings at mid- and high-zooms we’ve reduced average tile size by 30% and in some cases by 90%. As can be seen in the graph below, our median tile sizes are now under 40kB across all zooms.

Average tile file size by zoom, in kilobytes (256px tiles)

When measuring the 99th% worst case, we see even better improvements to file size. Most large tiles are now more than 50% smaller than version v0.10 tiles.

Variability in tile size by zoom – red line shows median, box out to the 1st and 3rd quartiles, and whiskers out to the 1% and 99% percentiles, in kilobytes (256px tiles)

We monitor these stats using the open source Scoville collection framework.

Data model consistency

The Mapzen Vector Tiles service is powered by Tilezen, our open source tiles project.

Version v1.0 has focused on seamlessly blending data (essentially the kind values) across the different sources per zoom, ensuring a consistent data model regardless of data source. We also introduce a new kind_detail property that aggregates across multiple OpenStreetMap source tags for layers like roads.

Mapzen vector tiles mash together several major open data sources and we owe a tremendous debt of gratitude to the individuals and communities which produced them. Specifically Natural Earth at low-zooms, OpenStreetMap at mid- and high-zooms, and Who’s On First at high-zooms.

Each data source has its own data model, and earlier versions of the vector tile service took a hands off approach, passing through raw or lightly transformed values from each. With version v1.0 of the Mapzen vector tile service we now normalize all kind values into a standard Tilezen data model based primarily on OpenStreetMap convention.

Attribution is required for many of our data sources. See the Attribution documentation for more information.

Data model interoperability

While the Tilezen data model used in Mapzen vector tiles is optimized for display, we have taken a generic interoperability approach to support many different map styles and map renderers besides our own Tangram. Please copy our data model!

The Tilezen semantic versioning documentation details the existing data properties, values, and our promises around them and is excerpted below.

Tilezen data model overview:

• common - layers, property names, and kind values are generally available across all features in a Tilezen response.
  • Establishes basic selection of features and their arrangement into specific named layers.
  • Core properties needed for display and labeling of features:
  • Special bits that make vector tile content interoperably Tilezen, including kind, kind_detail, landuse_kind, kind_tile_rank, min_zoom, max_zoom, is_landuse_aoi, sort_rank, boundary, and maritime_boundary.
  • Fundamental properties like name (including localized names), id, and source included on most every feature.
• common-optional - These are meant to be part of a common set, but may not be present because they aren’t relevant or because we don’t have the data (primarily feature properties).
  • Used to refine feature selection.
  • Lightly transformed interoperable Tilezen properties based on original data values. Examples include: country_capital, region_capital, bicycle_network, is_bridge, is_link, is_tunnel, is_bicycle_related, is_bus_route, walking_network, area, left & right names and localized name:* values on lines, and left & right id values on lines.
  • Fundamental properties like ref, colour, population, elevation, cuisine, operator, protect_class, and sport.
• optional - These are the properties of a specific, less important kind of feature, or generally present across all features of a kind but only in exceptional cases.
  • Often used to decorate features already selected for display.
  • Additional properties like capacity and covered.

Get an API key

To use the Mapzen Vector Tiles service, you should first get a developer API key. Sign in at https://mapzen.com/developers to create and manage your API keys, it’ll only take a minute (or two).

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, and optionally, give it a name so you can remember the purpose of the project.
4. Copy the key into the terrain URL where mapzen-xxxxxxx represents your key.

Tell me more

Complete documentation for the Mapzen Vector Tiles service is available from: https://mapzen.com/documentation/vector-tiles/

We also have a Gitter chat room: join the conversation.

Curious how Tilezen works or want to help out? The contributing docs are worth a read.

General improvements

We’ve improved a few things since v0.10:

• tilejson: Major upgrade to reflect all layers and properties for applications like Mapbox Studio and Tangram Play.
• general: More geometries are valid, especially in MVT format.
• general: Better attributing of source to OpenStreetMap for pois, transit, and other layers.
• roads layer: To support highway shields a new shield_text property has been added and existing network values have been normalized. Multiple shields are supported via optional all_networks and all_shield_texts lists. (The ref property remains available but is less useful for shield construction.)
• boundaries layer: New map_unit lines.
• buildings layer: Features of building_part may receive a root_id corresponding to the building feature, if any, with which they intersect.
• pois and landuse layers: Added graveyard, camp_site, and art gallery.

Breaking changes

Going forward we will adhere to semantic versioning (semver) and have added documentation detailing the promises the open source Tilezen project makes about major, minor, and patch versions and data model changes.

Of special note in the v1.0 release, the draw order of map features should now be keyed off sort_rank (was sort_key), language codes are normalized to 2-chars ISO langues, and city place labels (now locality) and state boundaries lines (now region) will break unless care is taken to update map stylesheets.

Pay special attention to low-zoom kind values – they were originally passed through raw from Natural Earth but are now normalized. We also dropped scalerank values from Natural Earth, mapping them instead into min_zoom values and added min_zoom values for all features in all layers.

Additionally, developers who used to parse buildings tiles for urban modeling at zoom 13 will no longer get back full data (use zoom 16 instead).

Getting to final v1.0 tiles we’ve broken a few things:

• boundaries layer: New locality kind is used for all city-like features, and region is used for state- and province-like features.
• buildings layer: features are merged at zooms 13, 14, and 15, and height values are quantized and some properties are removed at those zooms (but a new scale_rank property is added to distinguish groups of big buildings from groups of small buildings). Values previously found in kind are moved to kind_detail, and a value whitelist is applied.
• landuse layer: Rename several kind values to distinguish natural_wood from wood, natural_forest from forest, and natural_park from park.
• landuse-labels layer: has been removed in favor of features in the landuse layer and pois layers. (We marked it as deprecated several releases ago.)
• places layer: To reduce file sizes country labels were removed from zooms 0 and 1.
• places layer: New locality kind is used for all city-like features, and region is used for state- and province-like features. Capitals are now indicated as country_capital (was capital) and region_capital (was state_capital).
• pois layer: Some kinds were renamed to distinguish aeroway_gate from gate, specify gas_canister shops (was gas which was confusing with automotive gas stations), and split off ski_rental if a ski feature was primarily a rental facility.
• transit layer: route_name on line geometries is now simply name.
• Natural Earth kind values: Features sourced from Natural Earth now have normalized kind value in layers like boundaries, landuse, places, and roads layers.
• OpenStreetMap kind values: All kind values in the places and boundaries layers now follow Who’s On First placetype hierarchy.
• roads layer: Remove aerialway, highway, piste_type, and railway in favor of coalescing their values into a new kind_detail property.
• pois and landuse layers: cuisine and sport properties are dropped but their values moved to new kind_detail property.
• pois and landuse layers: Reclassify some national forest, park, national_park and other “green” areas based on their operator, protect_class, and other factors (and normalize operator values).
• pois and landuse layers: Change min_zoom so smaller, less important features are only included at later map zooms.
• places layer: Adjust min_zoom values for Natural Earth at the low-zooms and Natural Earth and OpenStreetMap localities at mid- and high-zooms to reduce label crowding.
• buildings and landuse layers: remove label placements from low- and mid zooms. Important landuse labels moved to the pois layer; the remainder are intended for text only labeling.

Read the docs

Check out the full story in the v1.0.0 changelog for new features and even more breaking changes.

Like any good drama, the Mapzen Vector Tile service has evolved over the season, with more than a dozen plot twists since v0.1 that we’ve listed below. Here’s to v1.0 and the upcoming season!

Vector tile timeline

• v0.1 (May 2015): Initial release, largely based on Michal Migurski’s vector tile project [1 and 2]. blog post
• v0.2pre (July, Aug 2015): Added dozens of new features in the landuse and pois layers and add extra tags like sport, religion, and cuisine. Also refined high-zoom feature visibility.
• v0.2 (Sept 2015): Add landuse_kind intercut for roads. Add water boundary (coastline) lines. Add address labels.
• v0.3 (Sept 2015): Show early national park and park polygons. Refine transition from Natural Earth to OpenStreetMap. Add sort_key for landuse polygons to prevent z-fighting.
• v0.4 (Oct 2015): adjust balance of pois and landuse labels, add de-duplicated label positions for water and buildings. Boundaries based on OSM relations include left and right localized names, and maritime boundaries. Added ferry and airport runways lines.
• v0.5 (Nov 2015): Switched to using neighbourhoods from Who’s On First, started refining High Road logic for more rail, aerialway, pedestrian features. Stopped duplicating buildings into the landuse layer. Filter out duplicate feature labels in pois, landuse, and buildings layers. Add kind_tile_rank to stations.
• v0.6 (Dec 2015): Hospitals, schools, and parking lot fixes. Added beaches, highway exits, road junctions, ice creme shops, toy stores, wine shops, alcohol shops, railway platforms, and pier lines. Refine zoom ranges for subway stations and zoos. Add winter sports pistes. Adds IATA codes to airports.
• v0.7 (Jan 2016): Road merging at low- and mid-zooms. Adds additional POIs for fitness centers, swimming pools, prisons, and airport gates. Clip buildings to 3x tile. Zoo and tourist attraction fixed up.
• Jan 2016: Station relations blog post
• Feb 2016: Blog post recapping v0.7, preview v0.8, and promoting new documentation.** blog post
• v0.8 (March 2016): Move to zoom 16 max tile (was 18). Add and revise sort_key values on all layers to reduce z-fighting. Add pois for International Women’s Day including childcare, dentist, doctor, toilets and slew of other features including more water labels, hardware stores. Revise station tile_kind_rank with more data.
• Mar 2016: Optimized global content distribution network for Europe, USA, and Asia. Dropped OpenScienceMap format.
• v0.9 (March 2016): OSM Transit! More revisions to station tile_kind_rank based on transit types and adjust transit feature zoom ranges and optional root_relation_id. Indicate if road is used for bus routes. Big SQL > CSV filter logic refactor.
• v0.10 (May 2016): Huge number of hiking, pedestrian, and bike improvements for Walkabout style, including early zoom paths. Waterfall, peaks islands. Start normalizing all Natural Earth and OpenStreetMap kinds and sources. More CSV > YAML filter logic refactor, and database triggers. blog post
• June 2016: Scoville starts monitoring production
• June 2016: Tilezen github org created!
• June 2016: Started enforcing vector tile keys (for on-demand path)
• v1.0-pre1 (July 2016): Start of major breaking changes for v1.0 release. New URL endpoint, reclassify bunch of features roads, boundaries, places, pois, landuse, and buildings layers. Reduce file size by removing some features and by merging buildings at mid-zooms. Adds indoor corridors, sidewalks, toll booths, camp sites, rest areas, and localized neighbourhood names. Add ability to generated buffered MVT format.
• v1.0-pre2 (Aug 2016): Low- and mid-zoom landuse merging. More normalization between Natural Earth and OpenStreetMap. Major changes for landuse and pois layers to improve consistency. Major changes to the places layer. Add new kind_detail property coalesce for roads features & etc. Adds explicate road shields. Fractional min_zooms values on all features in all layers. Major TileJSON upgrades. Semantic versioning doc.
• v1.0-pre3 (Sept 2016): New URL pattern, again. Fix boundary min_zooms. Add min_zoom to all features. Major fixes for national park, parks, and forest kind assignments based on operator and protect_class. Major adjustments to zoom ranges for landuse and pois.
• v1.0 final (October 2016): Fix MVT format geometry errors in land & water.

Feedback

Have any feedback on the vector tiles? Please direct feedback to Nathaniel Vaughn Kelso, our Chief Cartographer, at hello@mapzen.com!

image via Cooper Hewitt, Tile (USA), 19th–20th century; Manufactured by Trent Tile Company ; glazed stoneware; H x W x D (laying flat): 10.5 x 10.5 x 1.2 cm (4 1/8 x 4 1/8 x ½ in.); Gift of Florence Barnes; 1981-56-77