CARTO Basemaps

Does CARTO provide a basemap service?

Yes. We provide a basemap service using vector tiles, and we make them automatically available in all the components in the CARTO platform (Builder, Workflows, etc...), for all users.

We also serve a set of raster (PNG) basemaps at basemaps.cartocdn.com, which predate the vector service and are widely used from Leaflet and OpenLayers. They remain available and keep receiving data updates; they require an API key.

Our basemaps are also compatible with Maplibre GL JS, so that developers using deck.gl and CARTO for Developers can make use of it in their own applications.

The data for the CARTO basemaps is based on OpenStreetMap. Our basemaps are fully managed and powered by CARTO, including our own CDN, which makes them performant, scalable and customizable. Developers and users can choose between multiple predefined basemap styles, or even design their own styles following the OpenMapTiles specifications.

What is the pricing for CARTO basemaps? Is it free?

There is a free tier, and how much of it you get depends on how you use the maps. Anyone can request an API key; you do not need a CARTO account. The registration form asks whether your use is commercial; if that changes, write to support-basemaps@carto.com and we update it.

Non-commercial use — personal, research, teaching, non-profit — is free up to 5 million tile requests per calendar month.
Commercial use is free up to 1 million tile requests per calendar month. Above that you need one of two plans, bought by card from your dashboard: Basemaps Commercial, $500 a month or $5,000 a year paid up front, for up to 10 million requests a month; or Basemaps Commercial Plus, $1,500 a month or $15,000 a year, for up to 50 million. Prices are plus applicable taxes; cancel any time, the paid term runs to its end. Full detail on the basemaps page.

Requests are counted across all the keys on your account and across both the raster and vector services. Calendar months are counted in UTC.

Two conditions apply to free use:

Attribution must stay visible. CARTO and OpenStreetMap must be credited on every map, as described in attribution. This is what the free tier is in exchange for.
Your key is yours. Keys are per-customer and must not be shared or reused across unrelated projects.

Above the free allowance, what happens depends on the use. If it is non-commercial, get in touch and we will normally raise the limit at no charge. If it is commercial, requests above 1 million a month need a Basemaps Commercial plan (Commercial to 10 million, Commercial Plus to 50 million). Already on a plan? You can move to a larger one from your dashboard. Above 50 million a month, or for anything custom, talk to us.

Basemaps are included in every CARTO plan. CARTO customers and CARTO grant holders do not need the Commercial plan; your limits are set by your agreement rather than by the allowances above.

Full terms are in the CARTO Basemaps Terms and Conditions.

Why do I see an "API key required" watermark?

If your map shows no streets or labels, only tiles reading "API KEY REQUIRED · carto.com/basemaps/apikey" on a blank background, they are being requested from our raster basemap endpoint without a usable API key.

Since 25 September 2026, raster tiles are no longer served without a key. Until you add one, the map shows that notice instead of the basemap. (Before that date, the map stayed visible behind a watermark.)

Why we did this. CARTO has given these basemaps away for many years, and we would like to carry on doing that. The difficulty is that 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 tell a student project apart from a company running a product on our tiles, and cannot plan the service properly. Keys fix that, and they let us set the free tier much higher than we could when usage was anonymous.

How to fix it. Request an API key, then add it to your tile URL as a key parameter:

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

A key is free (see What is the pricing for CARTO basemaps? Is it free? for the allowances), it takes a minute, and you do not need a CARTO account.

Added a key and still see the notice? Your browser caches tiles, so hard-refresh the page or open it in a private window. If it persists, check that the key is copied in full and exactly as issued: an incomplete key, or one with its letters changed to upper case, is treated as no key at all.

If you use basemaps inside the CARTO platform — Builder or Workflows — this does not affect you and there is nothing to do.

Please do not try to remove or hide the notice. Section 3.d of the terms requires that CARTO's notices and attribution stay visible, and a key is free — just ask us for one.

Why are my tiles refused (403) when my key has website restrictions?

A key with website restrictions only serves tiles to pages on the hosts you listed in the Basemaps dashboard. Every other request gets a 403, and the map shows blank tiles. In the browser console the tile request may also appear as a CORS error.

Check these, in this order — they cover almost every case we see:

You are testing on your own machine (localhost, 127.0.0.1). Create a separate key for local development: it can list localhost, 127.0.0.1 and *.localhost, but a key that lists them cannot also list public sites.
- Enter the host without the port. IPv6 ([::1]) is not supported, so use localhost or 127.0.0.1.
The page sends no Referer.
- A Referrer-Policy: no-referrer header or <meta name="referrer"> tag breaks every map.
- same-origin breaks image-tile libraries (Leaflet, OpenLayers raster layers). MapLibre GL JS and Mapbox GL JS still work, because they send an Origin.
- Native and desktop apps, file:// pages and server-side requests send none.
- The browser default is fine.
- To check: open your browser's developer tools → Network → pick a tile request → Request headers → Referer.
Hosts must match exactly. www.example.com and example.com are different hosts, so list both. *.example.com covers subdomains but not example.com itself. Enter the host only: no https://, path or port.
A subdomain or another site is not in the list.
Preview deployments (Vercel, Netlify, Lovable, Cloudflare Pages…) get a new hostname on every deploy. Add a wildcard such as *.your-project.vercel.app, or use a separate key.
Testing with curl needs the header. Without it, a restricted key always returns 403:
```
curl -H 'Referer: https://yoursite.com/' '<tile URL>'
```
With a mobile-app restriction, the app must send the headers shown in the dashboard: X-Android-Package and X-Android-Cert, or X-Ios-Bundle-Identifier. If you enable several restriction types, a request must pass all of them.

Two things to know while you fix it:

Changes you save in the dashboard apply within seconds. Your browser may keep a refused tile for up to a minute, so hard-refresh the page.
The "refused" counter on a key is a month-to-date total. It will not go down after you fix things.

Still stuck? Email support-basemaps@carto.com with the tile URL and the Referer your browser sends.

Should I move from raster to vector basemaps?

Yes, and we would recommend it regardless of the key requirement. Our vector basemaps are better on every axis that matters:

Sharper cartography — crisp at any zoom level and on any display density, with no separate @2x request to think about.
Restyleable at runtime. Colours, labels and layer visibility can be changed in the browser instead of being baked into a PNG.
Cheaper and faster to serve, which is a large part of how we can afford to keep the free tiers generous.

Both vector and raster basemaps keep receiving data updates; raster is not being retired.

Only the raster basemaps require a key today. Vector styles still load without one. That said, we recommend every basemap user request a key now, whichever they use: we may extend the key requirement to vector in future, and having one already in place makes that a change you never notice rather than an interruption.

Migrating means moving from a tile-URL template to a MapLibre GL JS style URL:

// Before — raster tiles in Leaflet
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/attribution/">CARTO</a>',
  subdomains: 'abcd', maxZoom: 20
}).addTo(map);

// After — vector style in MapLibre GL JS
const map = new maplibregl.Map({
  container: 'map',
  style: 'https://basemaps.cartocdn.com/gl/voyager-gl-style/style.json?key=YOUR_KEY'
});

Raster style

Vector equivalent

rastertiles/voyager

https://basemaps.cartocdn.com/gl/voyager-gl-style/style.json

light_all

https://basemaps.cartocdn.com/gl/positron-gl-style/style.json

dark_all

https://basemaps.cartocdn.com/gl/dark-matter-gl-style/style.json

Attribution requirements are unchanged — see attribution.

How frequently does CARTO update its basemaps?

At a minimum, CARTO updates the underlying data for its vector basemaps at least once a year, including new roads, labels, areas, and other data points. Most years we provide updates every 3 or 6 months so that data is fresh and up-to-date, but the schedule and frequency is not guaranteed.

The raster basemaps are on the same data and keep receiving data updates. They are not being retired.

Can I use other basemaps in CARTO?

Yes! While customers and grantees can automatically make use of our basemaps, you can use any other basemap service of your preference:

CARTO provides out-of-the-box integration for Google Maps basemaps in Builder.
Admins can configure additional custom basemaps that will be available for their users in Builder
Developers can integrate any basemap provider in their CARTO + deck.gl applications.

I already use the basemaps commercially. What changes for me?

From 23 September 2026, commercial use above 1 million tile requests a calendar month needs a Basemaps Commercial plan. If your key was registered before 23 September 2026 and you use it commercially, it keeps working as it is until 30 November 2026. Between now and then, check your dashboard: if you serve less than 1 million requests a month, nothing changes for you. If you serve more, buy a plan from the dashboard before that date, or talk to us if you need more than 50 million a month.

I am a CARTO customer. Do I need to buy anything?

No. Basemaps are included in every CARTO plan, with limits set by your agreement rather than by the free allowances above. Inside the CARTO platform — Builder and Workflows — there is nothing to set up. If you registered a basemaps key with an e-mail address for a project of your own, write to support-basemaps@carto.com with the account ID shown on your dashboard, and we mark the account as covered.

PreviousDeployment Options

NextCARTO for Education

Last updated 1 day ago

Was this helpful?