After March 1, 2017, all access to the Mapzen Tile service will require an API key.

Be sure to update any apps that may be sending keyless requests. Any requests for vector or terrain tiles sent without an API key will soon return 401 and 429 errors.

Mapzen provides a generous free tier of API usage when you register for a Mapzen developer account. Sign up today!

See examples below on how to add an API key to Tangram and mapzen.js.

API keys are required

Mapzen’s mapping APIs enable developers to integrate maps, search, mobility, and place data into web, mobile, and desktop applications. When you register for a Mapzen developer account you are able to access our services with an API key, a code that uniquely links API usage inside your application with your account without needing a password.

Mapzen’s web services are resources shared by all our users. We use rate-limiting through API keys to ensure you get the maximum use of the generous limits associated with your account, and to help prevent individual users from degrading system performance for everyone.

In the past, it has been possible to access Mapzen’s services without an API key, but at significantly reduced rate limits compared to the levels available when passing an API key. We expected this keyless usage ability to be used only for trying out our services and training purposes, such as in code samples in technical documentation. However, some developers have relied on keyless access in production apps, and this has caused heavy server loads and poor experiences.

We have identified many cases in which end-users of apps that integrate Mapzen’s services have experienced broken maps and missing data after exceeding keyless access limits. Because the map works properly when tested, it is typical that developers are unaware that a problem exists, unless their users make the effort to report it.

If you use an API key, however, you can monitor the health of your application and see exactly what your users see.

Because all users should be able to enjoy speed, reliability, and good user experiences, you must include an API key with your request to Mapzen services. This is enforced March 1, 2017 for the Mapzen Vector Tile and Terrain Tile services. After that, the server will return error messages, such as HTTP status codes of 401 and 429, when you attempt to use our APIs without a key. These error messages help you identify issues sooner so you can correct them before they reach your users.

Note that this is in addition to the previous announcement that Mapzen basemap styles require an API key in this same timeframe.

API keys will be enforced for other Mapzen services, such as Mapzen Search and Mapzen Mobility, in the future; watch the Mapzen blog for dates. In the meantime, start preparing by updating your applications to use an API key.

What you need to do

There are two things you need to do:

1. Sign up for a free API key at https://mapzen.com/developers.
2. Use it in all your requests to Mapzen’s APIs.

If you are already following both of these, then nothing changes for you. You do not need to do anything further.

If not, you must take action and integrate Mapzen API keys into your apps. The simplest and most common way to include an API key is for your app to employ a single key with enough capacity to cover all of your users’ usage. Contact us if you need rate limits above the default levels.

If your app currently provides an option for users to enter their own Mapzen API keys, you should indicate that this setting is required, or redesign your app to follow the centralized key model.

Examples

Below are examples of how to add an API key in Tangram YAML, Tangram JS and Mapzen.js:

Example Tangram YAML usage:

import: https://mapzen.com/carto/refill-style/6/refill-style.yaml

global:
  sdk_mapzen_api_key: mapzen-xxxxxx

Example Tangram JS usage:

var layer = Tangram.leafletLayer({
  scene: {
    import: 'https://mapzen.com/carto/refill-style/6/refill-style.yaml',
    global: { sdk_mapzen_api_key: 'mapzen-xxxxxx' }
  });

Example Mapzen.js usage:

<script>
  L.Mapzen.apiKey = 'mapzen-xxxxxx';

  var map = L.Mapzen.map('map', {
    center: [40.8041, -124.1506],
    zoom: 15,
    maxZoom: 20,
    tangramOptions: {
      scene: L.Mapzen.BasemapStyles.Refill
    }
  });
</script>

See the Mapzen developer overview for more information on how to create and use API keys.

API keys for your testing and training needs

We are working on a system to support the original keyless access use cases of demos and testing. Future enhancements will allow you to copy code examples from technical documentation and paste them directly into your projects – check the Mapzen blog for updates.

Preview image via Cooper-Hewitt: 19th century glazed pottery, Museum purchase through gift of Mary Hearn Greims.