Merge pull request #525 from mapzen/nvkelso/docs

Move docs into main project repo

Author: nvkelso

README.md

@@ -0,0 +1,15 @@
+# Mapzen Vector Tile documentation
+
+This repository contains documentation for Mapzen's Vector Tile service.
+
+* [index.md](index.md) - This is where all the good stuff is.
+* [use-service.md](use-service.md) - Use the vector tile service, layers, and tile formats.
+* [api-keys-and-rate-limits.md](api-keys-and-rate-limits.md) - Don't ruin a good thing.
+* [display-tiles.md](display-tiles.md) - Display vector tiles in a map in Tangram, MapboxGL, D3, and other frameworks. 
+* [layers.md](layers.md) - Layers in the vector tile service detailed incuding available `kind` values and other tags.
+* [data-sources.md](data-sources.md) - Where does Mapzen's data come from?
+* [attribution.md](attribution.md) - Giving credit where credit is due, and the data licence requires it. 
+
+## Contributing
+
+If you have any comments on the documentation, you can drop a note as a GitHub issue, or fork it and add your own exercises.

docs/README.md

@@ -0,0 +1,22 @@
+# API keys and rate limits
+
+## Obtain an API key
+
+To use the Mapzen Vector Tile service, you should first obtain a free developer API key. Sign in at https://mapzen.com/developers to create and manage your API keys.
+
+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 Mapzen Vector Tiles, and optionally, give it a name so you can remember the purpose of the project.
+4. Copy the key into your code.
+
+## Rate limits
+
+Mapzen Vector Tiles is a free, shared service and rate limits are not currently enforced. 
+
+If an individual user abuses the service (especially by "vacuuming" or "scraping" tiles not pre-generated), the overall system performance will be degraded for the on-demand portion of the service for all users. Cached tiles will continue to be highly available for all users.
+
+We pre-generate popular map areas and those tiles are highly available and served directly via Fastly's edge cache. But map areas with low traffic are generated on-demand. 
+
+If you experience slow tile loading in a map area, it's likely because you are a first requester using on-demand tile generation. Subsequent loads of the same map area should be much faster because the tile is now available in the cache, and when the source OSM data changes in that map area we will update the tiles automatically for you.
+
+If you have questions, contact [tiles@mapzen.com](mailto:tiles@mapzen.com). You can also set up your own instance of [Vector Tiles](https://github.com/mapzen/vector-datasource), which has access to the same data used in the Mapzen Vector Tiles service.

docs/api-keys-and-rate-limits.md

@@ -0,0 +1,76 @@
+# Attribution
+
+
+Attribution is required for many of our data providers. Example language is provided below, but you are responsible for researching each project to follow their license terms. More details are available on the [Data Sources]() page. 
+
+**Required attribution:**
+
+>  © OpenStreetMap contributors, Who's On First
+
+**Full attribution for all projects:**
+
+>  © OpenStreetMap contributors, Who's On First, Natural Earth, and openstreetmapdata.com
+
+### Where to attribute
+
+Attribution needs to "appear in a place that is reasonable to the medium or means you are utilising." [Specific examples](http://wiki.osmfoundation.org/wiki/License#Where_to_put_it.3F) are given by the OSM Foundation and are generally best practices for giving credit to any source.
+
+## The fine print
+
+### OpenStreetMap
+
+`source:openstreetmap`
+
+[OpenStreetMap](https://www.openstreetmap.org/) is a community-driven, editable map of the world.  All OpenStreetMap data is licensed under the [ODbL](http://opendatacommons.org/licenses/odbl/), a [share-alike](https://en.wikipedia.org/wiki/Share-alike) license which also requires attribution.
+
+```
+© OpenStreetMap contributors
+```
+
+
+### openstreetmapdata.com
+
+We include OSM-derived water and earth polygons from [openstreetmapdata.com](http://openstreetmapdata.com) at mid- and high-zooms. This data is under the OSM ODbL license. 
+
+```
+© OpenStreetMap contributors
+```
+
+
+### Natural Earth
+
+`source:naturalearthdata.com`
+
+Natural Earth is a public domain dataset released as follows:
+
+```
+All versions of Natural Earth raster + vector map data found on this
+website are in the public domain. You may use the maps in any manner,
+including modifying the content and design, electronic dissemination,
+and offset printing. The primary authors, Tom Patterson and Nathaniel
+Vaughn Kelso, and all other contributors renounce all financial claim
+to the maps and invites you to use them for personal, educational, and
+commercial purposes.
+
+No permission is needed to use Natural Earth. Crediting the authors is
+unnecessary.
+```
+
+More details can be found on the Natural Earth [Terms of Use](http://www.naturalearthdata.com/about/terms-of-use/) page.
+
+
+### Who's On First
+
+`source:whosonfirst`
+
+Crediting [Who's On First](http://whosonfirst.mapzen.com) is recommended and linking back to their License is required. 
+
+```
+Data from Who's On First. <a href="http://whosonfirst.mapzen.com#License">License</a>
+```
+
+Who's On First makes use of a number of open data sources, some of whom **do** require attribution. Neighbourhood sources include: [Zetashapes](https://github.com/whosonfirst/whosonfirst-data/blob/master/LICENSE.md#zetashapes) (geometry), [Quattroshapes](https://github.com/whosonfirst/whosonfirst-data/blob/master/LICENSE.md#quattroshapes) (geometry), and [GeoPlanet](https://github.com/whosonfirst/whosonfirst-data/blob/master/LICENSE.md#geoplanet) (names). Please note that original sources may be modified.
+
+===
+
+See something funky? Please notify us if you believe that an open data project has not been properly noted!

docs/attribution.md

@@ -0,0 +1,53 @@
+# Data sources in Mapzen Vector Tiles
+
+Mapzen Vector Tiles are powered by several major open data sets and we owe a tremendous debt of gratitude to the individuals and communities which produced them.
+
+**Attribution is required** for many of our data providers. See the [Attribution]() document for more information. 
+
+## What is sourced at what zooms?
+
+Generally speaking, **Natural Earth** is used at low-zooms, and **OpenStreetMap** is relied on in mid- and high-zooms. Data from **openstreetmapdata.com** is used at the same zooms as the raw OSM data, and is derived from the OSM data. **Who's On First** neighbourhood labels generally come in at high-zooms. 
+
+When possible, we annotate individual map features in each tile with a `source` property. 
+
+
+## OpenStreetMap
+
+`source:openstreetmap`
+
+[OpenStreetMap](https://www.openstreetmap.org/) is a community-driven, editable map of the world. It prioritizes local knowledge and individual contributions over bulk imports, which often means it has excellent coverage even in remote areas where no large-scale mapping efforts have been attempted. OpenStreetMap contains information on landmarks, buildings, roads, and natural features.
+
+With its coverage of roads, POIs, landuse, as well as rich metadata, OpenStreetMap is arguably the most valuable dataset used by Mapzen Vector Tiles for general usage.
+
+All OpenStreetMap data is licensed under the [ODbL](http://opendatacommons.org/licenses/odbl/), a [share-alike](https://en.wikipedia.org/wiki/Share-alike) license which also requires attribution.
+
+## openstreetmapdata.com
+
+`source:openstreetmapdata.com`
+
+We include coastline-derived water polygons from [openstreetmapdata.com](http://openstreetmapdata.com) at mid- and high-zooms. This service was created by Jochen Topf and Christoph Hormann for the OpenStreetMap community and the general public and it rocks! 
+
+As they say, "The coastline in OpenStreetMap is often broken. The update process will try to repair it, but this does not always work. If the OSM data can't be repaired automatically, the data here will not be updated." 
+
+
+## Natural Earth
+
+`source:naturalearthdata.com`
+
+Natural Earth is a public domain map dataset available at 1:10m, 1:50m, and 1:110 million scales suitable for zooms 0 to 8. Featuring tightly integrated vector and raster data, with Natural Earth you can make a variety of visually pleasing, well-crafted maps with cartography or GIS software.
+
+Natural Earth was built through a collaboration of many [volunteers](http://www.naturalearthdata.com/about/contributors/) and is supported by [NACIS](http://www.nacis.org/) (North American Cartographic Information Society), and is free for use in any type of project (see our [Terms of Use](http://www.naturalearthdata.com/about/terms-of-use/) page for more information).
+
+More details can be found at: http://www.naturalearthdata.com/about/terms-of-use/
+
+
+## Who's On First
+
+`source:whosonfirst`
+
+[Who's On First](http://whosonfirst.mapzen.com) is Mapzen's place gazetteer, and is used to source neighbourhood labels.
+
+
+===
+
+Please notify us if you believe that an open data project has not been properly noted.

docs/data-sources.md

@@ -0,0 +1,47 @@
+# Display vector tiles in a map
+
+You can use Mapzen’s vector tile service with a variety of browser-based rendering software packages. Following the syntax of the library you are using, you need to specify the URL to the Mapzen vector tile service, the layers that you want to draw on the map, and styling information about how to draw the features. 
+
+## Tangram
+[Tangram](https://mapzen.com/projects/tangram) is a WebGL mapping engine designed for real-time rendering of 2D and 3D maps from vector tiles. More details are available on the [Tangram home  page](https://mapzen.com/projects/tangram).
+
+## D3
+D3 is a JavaScript visualization library that you can use to render to SVG format in your browser. [Mike Bostock](http://bl.ocks.org/mbostock) adapted d3.geo.til [to show OpenStreetMap vector tiles](http://bl.ocks.org/mbostock/5593150). To use D3 with Mapzen vector tiles, use either GeoJSON or TopoJSON format, which have similar syntax, or the Mapbox Vector Tiles format. The layer styling can be inline or referenced from a CSS file. 
+
+With D3, specifying the URL to the Mapzen vector tile service takes the form of 
+
+`d3.json("https://vector.mapzen.com/osm/{layers}/{zoom}/{x}/{y}.{format}", function(error, json)` 
+
+where .{format} can be .json for GeoJSON, .topojson for TopoJSON, or .mvt for Mapbox Vector Tiles.
+
+D3 uses a different zoom level than other map tiles. Default zoom for a map is set using `d3.geo.mercator` and `.scale()`. In this example, 21 is roughly equivalent to z13.
+
+```var projection = d3.geo.mercator()
+    .scale((1 << 21) / 2 / Math.PI)```
+    
+Upper and lower zoom levels are set using `d3.behavior.zoom()` and `.scaleExtent()`. In this example, the scale extent of 12 to 25 is roughly z4-z5 to z17:
+
+```.scaleExtent([1 << 12, 1 << 25])```
+
+See also the [D3 documentation on zoom behavior](https://github.com/mbostock/d3/wiki/Zoom-Behavior).
+
+See the examples at https://github.com/mapzen/d3-vector-tiles for more information. This repository has samples using each input format (see geojson.html, topojson.html, or index.html for .mvt).
+
+## MapboxGL
+[MapboxGL](https://www.mapbox.com/mapbox-gl/) is a JavaScript library used to render the Mapbox Vector Tiles protocol buffer format through OpenGL on both web and native platforms. 
+
+To specify Mapzen vector tile server as the source, use the following URL string, where .mvt is the file format.
+
+```  "sources": {
+    "osm": {
+      "type": "vector",
+      "tiles": ["https://vector.mapzen.com/osm/{layers}/{zoom}/{x}/{y}.mvt"]```
+
+See https://github.com/mapzen/mapboxgl-vector-tiles for a sample map of Mapzen vector tiles displayed in MapboxGL.
+
+## Hoverboard
+[Hoverboard](https://libraries.io/bower/hoverboard/v1.0.1) is a JavaScript library created by Tristan Davies to draw vector tiles as a Leaflet tile layer on the `<canvas>` HTML element of a web page. Hoverboard supports the Mapzen vector tiles in GeoJSON, TopoJSON, or Mapbox Vector Tiles format. 
+
+```window.xyz_tile_source_url = 'https://vector.mapzen.com/osm/{layers}/{zoom}/{x}/{y}.json';```
+
+See https://github.com/mapzen/hoverboard for more information. This repository has samples using each input format (see geojson.html, topojson.html, or index.html for .mvt). The Leaflet tile layer is defined in example.js, where you specify the Mapzen vector tile layers you want to render and the colors and symbols used to draw them.

docs/display-tiles.md

@@ -0,0 +1,59 @@
+#Mapzen Vector Tiles
+
+The [Mapzen vector tile service](https://mapzen.com/projects/vector-tiles) provides worldwide basemap coverage sourced from [OpenStreetMap](www.openstreetmap.org) and other open data projects, updated daily.
+
+![Contents of an example vector tile](images/vector-tile-example.png)
+
+Vector tiles are square-shaped collections of geographic data that contain the map feature geometry, such as lines and points. Information about how map features are drawn is maintained in a separate stylesheet file. 
+
+For many purposes, vector tiles are more flexible than raster tiles, which are images that already have the visual appearance of the map features pre-drawn. With vector tiles, there is no need to head back to the server and fetch a different set of tiles if you want to filter the output or change the style of a road or color of a building.
+
+Vector tiles make real-time rendering possible by sending the underlying data geometry and tags directly to the client, whether that’s a browser or a native mobile app. Buildings and roads can be rendered in different ways, or not at all, when the vector tile is downloaded, and changes happen instantly on the client's side. 
+
+With vector tiles you have the power to customize the content and visual appearance of the map. We're excited to see what you build!
+
+### Use Mapzen's Vector Tile Service
+
+To start integrating vector tiles to your app, you need a [developer API key](https://mapzen.com/developers). API keys come in the pattern: `vector-tiles-xxxxxxx`.
+
+* [API keys and rate limits](api-keys-and-rate-limits.md) - Don't abuse the shared service!
+* [Attribution requirements](attribution.md) - Terms of service for OpenStreetMap and other projects require attribution.
+
+#### Requestiong tiles
+
+The URL pattern to request tiles is:
+
+`https://vector.mapzen.com/osm/{layers}/{z}/{x}/{y}.{format}?api_key=vector-tiles-xxxxxxx`
+
+Here’s a sample tile in TopoJSON:
+
+`https://vector.mapzen.com/osm/all/16/19293/24641.topojson?api_key=vector-tiles-xxxxxxx`
+
+More information is available about how to [use the vector tile service](use-service.md) and specify custom layers in the service (though we recommend the default `all` layer).
+
+##### Formats
+
+The Mapzen vector tile service provides [tiles in a variety of formats](use-service.md#formats), including GeoJSON, TopoJSON, and MVT binary.
+
+**We recommend** `TopoJSON` format for desktop web development, and `MVT` format for native mobile development. The Mapzen server gzips tiles automatically, so the TopoJSON file format is comparable in file size to MVT over the wire, and it's much friendlier to debug.
+
+##### Drawing a map
+
+How to [draw the tile](display-tiles.md) in a browser is up to the vector-friendly visualization tool, such as SVG, Canvas, or WebGL. The [Tangram](https://mapzen.com/projects/tangram) rendering engine, which uses WebGL, is one way that you can draw the vector tile service in 2D and 3D maps.
+
+### How are vector tiles produced?
+
+Vector tiles are served by clipping geometries to the tile bounding box, and then simplified to match the zoom level to avoid unnecessary complexity at lower zoom levels. These geometries and features are also further processed to facilitate styling. 
+
+When changes are made to OpenStreetMap or another map [data sources](data-sources.md), rather than waiting for an image tile to be redrawn, only the geometry coordinates and feature attributes for that particular building or road need to be updated in the vector tile. 
+
+Depending on the URL syntax, Mapzen vector tiles can return all of the map data, or just individual [layers](layers.md), or combinations of layers, including water, earth, landuse, roads, buildings and points of interest.
+
+
+### Build from source
+
+If you are interested in setting up your own version of this service, follow these [installation instructions](https://github.com/mapzen/vector-datasource/wiki/Mapzen-Vector-Tile-Service), or you can also try this [Vagrant VM](https://github.com/mapzen/vagrant-tiles), which will additionally set up other tile components as well.
+
+### Credits
+
+This is based on the work of [Michal Migurski](http://mike.teczno.com/), and extends his [OSM.US-hosted vector tile service](http://openstreetmap.us/~migurski/vector-datasource/) with additional data and format support.