> For the complete documentation index, see [llms.txt](https://docs.carto.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.carto.com/faqs/carto-basemaps.md).
# CARTO Basemaps
[Does CARTO provide a basemap service?](#does-carto-provide-a-basemap-service)
[What is the pricing for CARTO basemaps? Is it free?](#what-is-the-pricing-for-carto-basemaps-is-it-free)
[Why do I see an "API key required" watermark?](#why-do-i-see-an-api-key-required-watermark)
[Why are my tiles refused (403) when my key has website restrictions?](#why-are-my-tiles-refused-403-when-my-key-has-website-restrictions)
[Should I move from raster to vector basemaps?](#should-i-move-from-raster-to-vector-basemaps)
[How frequently does CARTO update its basemaps?](#how-frequently-does-carto-update-its-basemaps)
[Can I use other basemaps in CARTO?](#can-i-use-other-basemaps-in-carto)
[I already use the basemaps commercially. What changes for me?](#i-already-use-the-basemaps-commercially.-what-changes-for-me)
[I am a CARTO customer. Do I need to buy anything?](#i-am-a-carto-customer.-do-i-need-to-buy-anything)
***
### **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](/carto-for-developers/key-concepts/carto-for-deck.gl/basemaps.md).
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](https://github.com/CartoDB/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](https://carto.com/basemaps/apikey/); you do not need a CARTO account. The registration form asks whether your use is commercial; if that changes, write to 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](https://carto.com/basemaps/#pricing).
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](https://carto.com/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](https://carto.com/request-live-demo/).
**Basemaps are included in every CARTO plan.** CARTO customers and [CARTO grant](https://carto.com/grants/) 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](https://carto.com/legal/basemap-terms/).
### **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](https://carto.com/basemaps/apikey), 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?](#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](https://carto.com/legal/basemap-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](https://dashboard.basemaps.carto.com). 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:
1. **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`.
2. **The page sends no `Referer`.**
* A `Referrer-Policy: no-referrer` header or `` 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`.
3. **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.
4. **A subdomain or another site** is not in the list.
5. **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.
6. **Testing with `curl`** needs the header. Without it, a restricted key always returns 403:
```
curl -H 'Referer: https://yoursite.com/' ''
```
7. **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 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:
```javascript
// Before — raster tiles in Leaflet
L.tileLayer('https://{s}.basemaps.cartocdn.com/rastertiles/voyager/{z}/{x}/{y}.png?key=YOUR_KEY', {
attribution: '© OpenStreetMap, © CARTO',
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](https://carto.com/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](/carto-user-manual/maps/basemaps.md#google-maps-basemaps).
* Admins can configure [additional custom basemaps ](/carto-user-manual/settings/customizations/configuring-your-organization-basemaps.md)that will be available for their users in Builder
* Developers can integrate [any basemap provider in their CARTO + deck.gl applications](/carto-for-developers/key-concepts/carto-for-deck.gl/basemaps.md).
### **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](https://carto.com/request-live-demo/) 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 with the account ID shown on your dashboard, and we mark the account as covered.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://docs.carto.com/faqs/carto-basemaps.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.