Request an API key for basemaps

CARTO basemaps now require an API key to continue using them. Read the information below and fill in the form to request one — it is free, and there is no approval queue.

Why am I required to use an API key?

CARTO has provided these basemaps to a great many people for years, and traditionally without any key at all. That is probably why you are reading this: something you built, inherited, or copied from a tutorial has been working quietly for a long time.

We are introducing keys for two reasons — the sheer volume the service now carries, and the need to control abuse. Without a key we cannot tell who is using the service or how much, which means we cannot warn anyone before they hit a limit, cannot separate a student project from a company running a product on our tiles, and cannot plan capacity honestly.

A key is free. What matters is understanding what it covers:

  • 5 million tile requests per calendar month, counted across both the raster and vector services. Go past it and we will get in touch rather than cut you off.
  • Intended for non-commercial use — personal projects, research, teaching, non-profits. Commercial projects are welcome and still get a key, but past the limit we may ask you to move onto a commercial agreement. Talk to us and we will find something that fits.
  • Keep the attribution visible. CARTO and OpenStreetMap attribution must stay on your maps. That is what the free tier is in exchange for.
  • The key is yours. Do not share it or reuse it across unrelated projects.

The requirement is arriving on our raster (PNG) basemaps first, but it is not a raster-only measure — it is coming to the vector basemaps as well. Whichever you use, the key you request today is the one you will need.

Get your key

Tell us your email, the domain you will use the basemaps on, and roughly what you are building. We email the key straight back — there is no approval queue and you do not need a CARTO account.

Then add it to your tile URL as a key parameter:

https://basemaps.cartocdn.com/rastertiles/voyager/{z}/{x}/{y}.png?key=YOUR_KEY

In Leaflet that looks like:

L.tileLayer('https://{s}.basemaps.cartocdn.com/rastertiles/voyager/{z}/{x}/{y}.png?key=YOUR_KEY', {
  attribution: '&copy; <a href="https://www.openstreetmap.org/copyright">OpenStreetMap</a>, &copy; <a href="https://carto.com/attributions">CARTO</a>',
  subdomains: 'abcd', maxZoom: 20
}).addTo(map);

If you still see the “API key required” watermark afterwards, force-refresh — your browser and our CDN both cache map tiles, so an old one can linger for a moment.

Using basemaps inside the CARTO platform? Builder, Workflows, and applications authenticated with your CARTO credentials are unaffected. There is nothing for you to do.

Vector basemaps vs raster

We run two basemap services. Raster (PNG) is the older of the two and is being retired; vector is better on every axis that matters:

  • Sharper cartography — crisp at any zoom and on any display density, with no separate @2x request.
  • Fresher data. We are considering stopping data updates to the raster basemaps, in which case that cartography stays where it is while vector keeps moving.
  • Restyleable in the browser — change colours, labels and layer visibility at runtime instead of baking them into a PNG.
  • Faster and cheaper to serve, which is a large part of how we can afford to keep the free allowance generous.

Your key covers both, so migrating later is one less thing to redo. The basemaps FAQ has a per-style migration table.

Don't forget to read the terms and conditions

Full terms are in the CARTO Basemaps Terms and Conditions — the parts most people need are the API key requirement, the fair use limit, and the attribution requirement.