add api key docs

api-reference.md

@@ -4,7 +4,45 @@ Mapzen basemaps offer several global properties to customize and extend the map.
 
 Not every basemap supports the full set of resources and the default styling of these assets is customized per Mapzen map style. See [Styles](styles.md) for what's supported.
 
-As the basemaps are still in active development we recommend peggging an import to a specific major version, eg: `5`. See the [versioning](versioning.md) doc for more details.
+As the basemaps are still in active development we recommend pegging an import to a specific major version, eg: `6`. See the [versioning](versioning.md) doc for more details.
+
+## Mapzen API keys
+
+Mapzen basemaps require setting a Mapzen API key to access related Mapzen vector tile and terrain tile services. 
+
+[Sign up](https://mapzen.com/documentation/overview/#developer-accounts-and-api-keys) for a Mapzen API key here.
+
+### sdk_api_key
+
+* `sdk_mapzen_api_key`: defaults to `''` (an empty string)
+
+Example **Tangram YAML** usage:
+
+```
+import: https://mapzen.com/carto/refill-style-more-labels/6/refill-style-more-labels.yaml
+
+global:
+    sdk_mapzen_api_key: mapzen-xxxxxx
+```
+
+Example **Tangram JS** usage:
+
+```
+var layer = Tangram.leafletLayer({
+    scene: { import: 'https://mapzen.com/carto/refill-style-more-labels/6/refill-style-more-labels.yaml', global: { sdk_mapzen_api_key: 'mapzen-xxxxxx' } },
+    attribution: '&copy; <a href="https://www.mapzen.com/rights" target="_blank">Mapzen</a>,  <a href="https://openstreetmap.org/copyright" target="_blank">OpenStreetMap</a>
+, and <a href="https://www.mapzen.com/rights/#services-and-data-sources" target="_blank">others</a>.'});
+```
+
+Example **Tangram ES** usage:
+
+```
+map->loadScene(
+    "https://mapzen.com/carto/refill-style-more-labels/6/refill-style-more-labels.yaml",
+    false,
+    { "global.sdk_mapzen_api_key", "mapzen-xxxxxx" }
+);
+```
 
 ## Language
 
@@ -16,10 +54,12 @@ If you ask for a language that isn't present in the data, it will automatically
 
 * `ux_language`: defaults to `false`
 
-Example Tangram usage:
+Example **Tangram YAML** usage:
 
 ```
-globals:
+import: https://mapzen.com/carto/refill-style-more-labels/6/refill-style-more-labels.yaml
+
+global:
     ux_language: fr
 ```
 
@@ -31,10 +71,12 @@ For instance, if someone reads French but not Japanese they would prefer to see
 
 * `ux_language_fallback`: defaults to `false`
 
-Example Tangram usage:
+Example **Tangram YAML** usage:
 
 ```
-globals:
+import: https://mapzen.com/carto/refill-style-more-labels/6/refill-style-more-labels.yaml
+
+global:
     ux_language: fr
     ux_language_fallback: en
 ```
@@ -65,10 +107,10 @@ Common language codes values include:
 
 To facilitate map customization and data visualizations several recommended sort orders are provided. The order properties abstract the values which work with specific versions of Mapzen vector tiles (see [feature ordering](https://mapzen.com/documentation/vector-tiles/layers/#feature-ordering) docs).
 
-Example Tangram usage:
+Example **Tangram YAML** usage:
 
 ```
-import: https://mapzen.com/carto/refill-style-more-labels/5/refill-style-more-labels.yaml
+import: https://mapzen.com/carto/refill-style-more-labels/6/refill-style-more-labels.yaml
 
 _layername:
     draw:
@@ -144,37 +186,77 @@ Some basemap styles support transit overlays.
 
 * `sdk_transit_overlay`: default `false`
 
-Example Tangram usage:
+Example **Tangram YAML** usage:
 
 ```
-import: https://mapzen.com/carto/bubble-wrap-style/bubble-wrap.yaml
+import: https://mapzen.com/carto/refill-style-more-labels/6/refill-style-more-labels.yaml
 
-globals:
+global:
     sdk_transit_overlay: true
 ```
 
 ## Default draw styles
 
-Custom draw styles for icons, point, line, and polygon overlays on the map. These set the feature order and blend order to be a standard overlay.
+Custom **draw styles** for icons, point, shield, line, and polygon overlays on the map. These set the feature order and blend order to be a standard overlay. For icons, point, and shield styles a default sprite is also set.
+
+Special `mz_*` **data sources** are available to automatically render content using the associated draw styles for point, shield, line, and polygon draw styles. To render features in one of these draw styles, create the specified `mz_*` data source.
+
+Example **Tangram YAML** examples for `mz_*` source names:
+
+```
+import: https://mapzen.com/carto/refill-style-more-labels/6/refill-style-more-labels.yaml
+
+sources:
+    mz_default_polygon:
+        type: GeoJSON
+        url:  https://example.com/filename.geojson
+```
 
 ### Icons
 
 * **draw style:** `icons`
 * **sprite:** multiple sprites supported in the `pois` texture, see [icons](icons.md)
 
+Example **Tangram YAML** usage:
+
+```
+import: https://mapzen.com/carto/refill-style-more-labels/6/refill-style-more-labels.yaml
+
+sources:
+    _my_source:
+        type: GeoJSON
+        url:  https://example.com/filename.geojson
+
+layers:
+    _my_layer:
+        data: { source: _my_source }
+        draw:
+            icons:
+                size: [[13, 18px], [16, 18px], [18, 22px]]
+                sprite: zoo
+```
+
 ### Points
 
 * **draw style:** `sdk-point-overlay`
 * **sprite:** `ux-search-active`
+* **data source:** `mz_default_point`
+
+### Shields
+
+* **draw style:** `sdk-shield-overlay`
+* **sprite:** `sdk_shield_1char`, `sdk_shield_2char`, `sdk_shield_3char`, `sdk_shield_4char`, `sdk_shield_5char`
+* **data source:** `mz_default_shield`
 
 ### Lines
 
 * **draw style:** `sdk-line-overlay`
+* **data source:** `mz_default_line`
 
 ### Polygons
 
 * **draw style:** `sdk-polygon-overlay`
-
+* **data source:** `mz_default_polygon`
 
 ## User experience
 
@@ -184,21 +266,21 @@ If you add a any of the following named data sources to the scene file (or updat
 
 ### Current location
 
-* **data source:** `mz_current_location`
 * **draw style:** `ux-location-gem-overlay`
 * **sprite:** `ux-current-location`
+* **data source:** `mz_current_location`
 
 ### Dropped pin
 
-* **data source:** `mz_dropped_pin`
 * **draw style:** `ux-icons-overlay`
 * **sprite:** `ux-search-active`
+* **data source:** `mz_dropped_pin`
 
 ### Search results
 
-* **data source:** `mz_search_result`
 * **draw style:** `ux-icons-overlay`
 * **sprite:** `ux-search-active`
+* **data source:** `mz_search_result`
 
 When a search feature is marked `state: inactive`, the following resources is used:
 
@@ -208,46 +290,46 @@ When a search feature is marked `state: inactive`, the following resources is us
 
 #### Route line
 
-* **data source:** `mz_route_line`
 * **draw style:** `ux-route-line-overlay`
+* **data source:** `mz_route_line`
 
 #### Progress along the route line
 
-* **data source:** `mz_route_location`
 * **draw style:** `ux-location-gem-overlay`
 * **sprite:** `ux-route-arrow`
+* **data source:** `mz_route_location`
 
 #### Starting location icon
 
-* **data source:** `mz_route_start`
 * **draw style:** `ux-icons-overlay`
 * **sprite:** `ux-route-start`
+* **data source:** `mz_route_start`
 
 #### Destination location icon
 
-* **data source:** `mz_route_destination`
 * **draw style:** `ux-icons-overlay`
 * **sprite:** `ux-route-stop`
+* **data source:** `mz_route_destination`
 
 #### Transit route line
 
 Each transit route segment could be a different "line" each with it's own `color` data driven styling. But some transit lines don't define a color, in those cases default to blue.
 
-* **data source:** `mz_route_line_transit`
 * **data source feature property:** `color`
 * **draw style:** `ux-transit-line-overlay`
+* **data source:** `mz_route_line_transit`
 
 #### Transit stop
 
 For major transit stops related to onboarding, offboarding, and transfers. If pass-thru stops are provided in the data source they will also be rendered (but are not in the general Mapzen Turn-by-Turn response).
 
-* **data source:** `mz_route_transit_stop`
 * **draw style:** `ux-icons-overlay`
 * **sprite:** `ux-transit-stop`
+* **data source:** `mz_route_transit_stop`
 
 #### Dashed route line
 
 Used to show walking segments of multi-modal routes.
 
-* **data source:** `mz_dash_line`
 * **draw style:** `ux-route-line-dash-overlay`
+* **data source:** `mz_dash_line`

styles.md

@@ -29,6 +29,7 @@ Bubble Wrap is only available in the "more labels" version.
 * Default draw styles
 * Basic user experience styles
 * Transit user experience styles
+* Mapzen API key
 
 **Not supported:**
 
@@ -66,6 +67,7 @@ A minimalist map style designed for data visualization overlays. Inspired by the
 * Default draw styles
 * Basic user experience styles
 * Transit user experience styles
+* Mapzen API key
 
 **Not supported:**
 
@@ -99,6 +101,7 @@ This outdoor style is perfect for hiking or getting out and about, with mountain
 * Default draw styles
 * Basic user experience styles
 * Transit user experience styles
+* Mapzen API key
 
 **Not supported:**
 
@@ -132,6 +135,7 @@ Will autonomous cars dream as they charge overnight? We’re pushing mapping to
 * Default draw styles
 * Basic user experience styles
 * Transit user experience styles
+* Mapzen API key
 
 **Not supported:**
 
@@ -165,6 +169,7 @@ A classic web map style for general mapping applications.
 * Default draw styles
 * Basic user experience styles
 * Transit user experience styles
+* Mapzen API key
 
 **Not supported:**
 
@@ -198,6 +203,7 @@ A dark, minimalist style that helps bright data overlays stand out. A great alte
 * Default draw styles
 * Basic user experience styles
 * Transit user experience styles
+* Mapzen API key
 
 **Not supported:**