Add description on how to set API key per style

[nvkelso]

Most the styles must be updated to allow this, though.

Question: /cc @bcamper

• Should Mapzen house styles styles continue to ship with Mapzen's API keys set or leave that blank?

If we remove it, then our product pages would need to set them on map init, and the Github repo index pages would also need to set them on init.

[nvkelso]

Confirmed this approach with Brett:

Using Tangram's JS API:

    var layer = Tangram.leafletLayer({
        scene: { import: style_file, global: { sdk_mapzen_api_key: 'mapzen-xxxxxx' } },
        attribution: '<a href="https://mapzen.com/tangram" target="_blank">Tangram</a> | &copy; OSM contributors | <a href="https://mapzen.com/" target="_blank">Mapzen</a>'
    });

The house style YAML files would change something like:

global:
    # Sign up for a Mapzen API key to enjoy higher rate limits
    # https://mapzen.com/documentation/overview/#developer-accounts-and-api-keys
    sdk_mapzen_api_key: ''     # set this value to your Mapzen API key

sources:
    mapzen:
        type: MVT
        url:  https://tile.mapzen.com/mapzen/vector/v1/all/{z}/{x}/{y}.mvt
        max_zoom: 16
        url_params:
            api_key: global.sdk_mapzen_api_key
    normals:
        type: Raster
        url: https://tile.mapzen.com/mapzen/terrain/v1/normal/{z}/{x}/{y}.png
        max_zoom: 15
        url_params:
            api_key: global.sdk_mapzen_api_key

(updated 2016.12.22 and again 2017.01.05)

[nvkelso]

/cc @kkowalsky

[kkowalsky]

hey @meetar do you mind double checking this?

[nvkelso]

The new sdk_mapzen_api_key global would be added to the API reference page, then the Tangram JS API stuff would go into get-started/#tangram. I believe Tangram ES is currently adding support for the same.

(updated)

[meetar]

@kkowalsky The example looks good, though I don't know anything about the sdk_mapzen_api_key parameter.

(updated)

[nvkelso]

@meetar the new sdk_mapzen_api_key will be added to house styles as a Tangram global property that'll I'll plumb thru as a URL param for sources.

(updated)

[nvkelso]

@blair1618 Does Tangram ES support url_params in sources yet? Can you link the related issue here, please?

[tallytalwar]

ES does support url_params in sources.

[nvkelso]

@tallytalwar Nice! What's the ES equivalent code snippet to JS's:

Scene.load({
      import: 'https://mapzen.com/carto/bubble-wrap-style/bubble-wrap.yaml',
      global: { sdk_mapzen_api_key: `XXX` }
    });

[matteblair]

In our C++ interface you could do this:

map->loadScene(
    "https://mapzen.com/carto/bubble-wrap-style/bubble-wrap.yaml",
    false,
    { "global.sdk_mapzen_api_key", "mapzen-xxxxxx" }
);

We're currently working on the Android interface for this (tangrams/tangram-es#1173).

(updated 2016.12.22 for global variable name and 2017.01.05 for example key)

[nvkelso]

(Bubble Wrap and Refill already support the general url_params syntax, but need to move towards generic SDK approach still.)