[FEAT] Support CARTO API Keys and Configurable Map Providers

[maxhayim]

Is your feature request related to a problem? Please describe.

Yes.

CARTO has started requiring API keys for access to its basemaps. Applications currently using CARTO tiles without authentication may begin displaying API key warnings or eventually lose access to those basemaps.

At the moment, there does not appear to be a way for users or administrators to provide their own CARTO API key.

This also highlights a broader issue: the application is dependent on specific map providers. Map providers can change their API requirements, pricing, rate limits, authentication methods, or availability over time.

Being dependent on a single hard-coded map source makes the mapping functionality vulnerable to those changes.

It can also limit users who may prefer another mapping provider because of:

• Better map coverage in their region
• Better satellite imagery
• Different map styles
• Existing API subscriptions
• Self-hosted deployments
• Privacy requirements
• Performance
• Rate limits
• Offline or locally hosted tile servers

Describe the solution you'd like

I would like the application to support configurable map providers, starting with the ability to provide a CARTO Basemaps API key.

For example:

Map Provider:
CARTO

CARTO API Key:
[________________________]

The application could then automatically append the configured API key to CARTO tile requests.

Example:

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

Multiple Map Providers

Ideally, the map settings should allow users or administrators to select from multiple map providers.

Possible providers could include:

CARTO
OpenStreetMap
Google Maps
Google Satellite
Google Hybrid
Google Terrain
MapTiler
Mapbox
Stadia Maps
Custom XYZ Tile Server
Custom Vector Tile Server

Providers that require authentication could expose an API key or token field when selected.

For example:

Map Provider:
Google Maps

Google Maps API Key:
[________________________]

Or:

Map Provider:
MapTiler

MapTiler API Key:
[________________________]

Google Maps Support

It would be particularly useful to support Google Maps Platform as an optional map provider.

Google Maps could provide options such as:

Roadmap
Satellite
Hybrid
Terrain

This would be especially useful for users who already have a Google Maps Platform API key or prefer Google's satellite imagery and mapping data for viewing nodes, routes, telemetry, coverage, and other geographically displayed information.

The Google Maps API key should be supplied by the user or administrator rather than bundled with the application.

Custom Map Provider

A Custom Map Provider option would also be extremely useful.

Advanced users could enter a compatible XYZ tile URL such as:

https://example.com/tiles/{z}/{x}/{y}.png

Or a provider requiring an API key:

https://example.com/tiles/{z}/{x}/{y}.png?key={api_key}

Possible configuration:

Provider Name:
My Custom Maps

Tile URL:
https://example.com/tiles/{z}/{x}/{y}.png

API Key / Token:
[________________________]

Attribution:
[________________________]

Maximum Zoom:
[____]

If vector tiles are supported by the map library, a similar option could eventually be provided for custom vector tile sources.

Suggested Settings Layout

Maps
────────────────────────────────

Map Provider:
[ CARTO ▼ ]

API Key:
[________________________________]

Map Style:
[ Voyager ▼ ]

────────────────────────────────

Available Providers:

○ CARTO
○ OpenStreetMap
○ Google Maps
○ MapTiler
○ Mapbox
○ Stadia Maps
○ Custom

────────────────────────────────

Custom Provider Settings

Tile URL:
[________________________________]

API Key / Token:
[________________________________]

Attribution:
[________________________________]

Maximum Zoom:
[____]

The available configuration fields could change depending on the selected provider.

Why this would be useful

This would make the map system significantly more flexible and future-proof.

If one mapping provider:

• Changes its API requirements
• Introduces API keys
• Changes its pricing
• Changes its rate limits
• Has an outage
• Discontinues a service
• Has poor coverage in a particular region

users could simply switch to another provider without requiring changes to the application itself.

It would also allow deployments to use whichever mapping service best fits their particular environment.

For larger or self-hosted deployments, this could be especially useful because they may already have existing accounts or infrastructure for:

• CARTO
• Google Maps Platform
• OpenStreetMap
• MapTiler
• Mapbox
• Stadia Maps
• Self-hosted tile servers

Describe alternatives you've considered

One alternative would be to replace CARTO entirely with another provider that currently does not require an API key.

However, this would only move the dependency from one provider to another.

The same problem could occur again if that provider later changes its API requirements, rate limits, pricing, or access policies.

Another option would be to hard-code a CARTO or Google Maps API key into the application.

I do not think this would be ideal because it could create issues involving:

• API usage limits
• Billing
• API key security
• Abuse
• Shared quotas
• Provider terms
• Rate limits

Allowing each installation or user to provide their own API key would keep usage associated with the appropriate account.

For this reason, I think the best long-term solution would be to create a provider abstraction for the mapping system rather than implementing another single hard-coded provider.

Additional context

CARTO API key information:

https://carto.com/basemaps/apikey/

Example CARTO tile request:

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

Google Maps Platform could also be offered as an optional provider using a user-supplied Google Maps API key.

Ideally, the implementation would separate the map interface from the underlying provider so additional providers can be added later without requiring major changes throughout the application.

Conceptually:

Application Map
       │
       ▼
Map Provider Interface
       │
       ├── CARTO
       ├── OpenStreetMap
       ├── Google Maps
       ├── MapTiler
       ├── Mapbox
       ├── Stadia Maps
       └── Custom XYZ / Vector Tiles

This would solve the immediate CARTO API-key issue while also making the mapping system much more flexible going forward.

[Yeraze]

Thanks for the detailed writeup! This isn't an exact duplicate of an existing issue, but most of the concrete asks here were already shipped very recently, so let me summarize what's already available before we scope what's left.

Already implemented

CARTO API key (#4934, merged in 4.15.x): There's now a dedicated, admin-configurable cartoApiKey setting. Once set, it's automatically appended to every CARTO raster and vector basemap request (src/config/cartoKey.ts), across the 2D map, embed views, and the traceroute widget — no more "API key required" watermark. Set it under Settings → Map Settings.

Custom / arbitrary tile providers (#654, PR #674, merged): MeshMonitor already supports a generic Custom Tile Server provider abstraction (src/config/tilesets.ts CustomTileset) with:

• Name, XYZ tile URL template ({z}/{x}/{y}), attribution, and max zoom — exactly the fields in your "Suggested Settings Layout"
• Both raster and vector (MapLibre GL style.json) tile sources
• An optional overlay layer (e.g. labels-over-satellite)
• Up to 50 custom tilesets per instance, selectable from the same tileset picker as the built-in options (independently for light/dark mode)

This already covers MapTiler, Mapbox, Stadia Maps, and self-hosted/offline tile servers today — since those are all standard XYZ endpoints, you can add them as a Custom Tile Server and just bake the API key into the URL template (e.g. https://api.maptiler.com/maps/streets/{z}/{x}/{y}.png?key=YOUR_KEY). See the docs: Custom Tile Servers.

Built-in presets today: OpenStreetMap, OSM HOT, CARTO Dark/Light (with the new key support), OpenTopoMap, and ESRI Satellite/Hybrid.

What's genuinely still missing

1. A curated "pick a provider from a dropdown, get provider-specific fields" UX — right now MapTiler/Mapbox/Stadia are reachable, but only via the generic Custom Tile Server form (you build the URL yourself), not a named preset with its own API-key field.
2. Google Maps Platform as a provider — this is a different shape of problem than the others. Google's raster/roadmap/satellite/hybrid/terrain tiles aren't a plain XYZ endpoint you can query directly under their terms of service; using them properly means integrating the actual Google Maps JS SDK (or @vis.gl bindings) for that view rather than adding another TileLayer URL, which is a meaningfully larger change than the rest of this request.

Given the bulk of the request is already covered by shipped code, could you confirm which of the two remaining items above still matter to you — the friendlier named-provider picker, Google Maps support specifically, or both? That'll determine whether this becomes a small UX-polish issue or a larger scoped feature, and I'll post a plan here once that's clear rather than guessing at scope.

-- Authored by Roger 🤓

---

Generated by Claude Code