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:
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:
- New URL scheme!
- Smaller file sizes, especially at low- and mid-zooms for better client-side performance.
- Data model changes for improved consistency of
kindvalues and other properties across all zoom levels, and introduce a new
kind_detailproperty that aggregates across multiple OpenStreetMap source tags for layers like roads.
- 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.
- Mapbox Vector Tile:
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
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.
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.
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
- Fundamental properties like
name(including localized names),
sourceincluded 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:
area, left & right names and localized
name:*values on lines, and left & right
idvalues on lines.
- Fundamental properties like
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
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).
- Go to https://mapzen.com/developers.
- Sign in with your GitHub account. If you have not done this before, you need to agree to the terms first.
- Create a new key, and optionally, give it a name so you can remember the purpose of the project.
- Copy the key into the terrain URL where
mapzen-xxxxxxxrepresents 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.
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
sourceto OpenStreetMap for pois, transit, and other layers.
- roads layer: To support highway shields a new
shield_textproperty has been added and existing
networkvalues have been normalized. Multiple shields are supported via optional
refproperty remains available but is less useful for shield construction.)
- boundaries layer: New
- buildings layer: Features of
building_partmay receive a
root_idcorresponding to the building feature, if any, with which they intersect.
- pois and landuse layers: Added
camp_site, and art
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_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
localitykind is used for all city-like features, and
regionis used for state- and province-like features.
- buildings layer: features are merged at zooms 13, 14, and 15, and
heightvalues are quantized and some properties are removed at those zooms (but a new
scale_rankproperty is added to distinguish groups of big buildings from groups of small buildings). Values previously found in
kindare moved to
kind_detail, and a value whitelist is applied.
- landuse layer: Rename several
kindvalues to distinguish
- 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
localitykind is used for all city-like features, and
regionis used for state- and province-like features. Capitals are now indicated as
- pois layer: Some kinds were renamed to distinguish
gaswhich was confusing with automotive gas stations), and split off
skifeature was primarily a rental facility.
- transit layer:
route_nameon line geometries is now simply
- Natural Earth kind values: Features sourced from Natural Earth now have normalized
kindvalue in layers like boundaries, landuse, places, and roads layers.
- OpenStreetMap kind values: All
kindvalues in the places and boundaries layers now follow Who’s On First placetype hierarchy.
- roads layer: Remove
railwayin favor of coalescing their values into a new
- pois and landuse layers:
sportproperties are dropped but their values moved to new
- pois and landuse layers: Reclassify some national
national_parkand other “green” areas based on their
protect_class, and other factors (and normalize
- pois and landuse layers: Change
min_zoomso smaller, less important features are only included at later map zooms.
- places layer: Adjust
min_zoomvalues for Natural Earth at the low-zooms and Natural Earth and OpenStreetMap
localitiesat 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
cuisine. Also refined high-zoom feature visibility.
- v0.2 (Sept 2015): Add
landuse_kindintercut 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_keyfor 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
- 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_keyvalues 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_rankwith 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.
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