From 774fdf474fb1f3944ad16d203ab171d41bcbd95f Mon Sep 17 00:00:00 2001 From: Nilay Date: Thu, 19 Nov 2026 16:46:13 +0530 Subject: [PATCH] Add api_key option to TileLayer for providers that need a key CARTO now only serves its basemaps to requests that carry an API key, and xyzservices strips the key placeholder and warns when none is given. Folium had no way to pass a key through for built-in tile names, so `TileLayer("CartoDB Positron")` always rendered watermarked tiles, and an `apikey=` kwarg silently ended up as an unused Leaflet option. `TileLayer` now takes `api_key`, which fills the provider's token placeholder whatever the provider calls it (`apikey`, `accessToken`, `subscriptionKey`, ...). It raises a ValueError when used with a custom URL or a provider that has no placeholder, instead of being ignored. Also note the key requirement in the Map and TileLayer docstrings and stop using CartoDB tiles in the Map and DualMap docstring examples without a key. Refs #2321 --- folium/folium.py | 8 ++++++- folium/plugins/dual_map.py | 2 +- folium/raster_layers.py | 42 +++++++++++++++++++++++++++++++++++-- tests/test_raster_layers.py | 41 ++++++++++++++++++++++++++++++++++++ 4 files changed, 89 insertions(+), 4 deletions(-) diff --git a/folium/folium.py b/folium/folium.py index 87067b3680..aea68408b7 100644 --- a/folium/folium.py +++ b/folium/folium.py @@ -102,6 +102,9 @@ class Map(JSCSSMixin, Evented): Explore more provider names available in ``xyzservices`` here: https://leaflet-extras.github.io/leaflet-providers/preview/. + Some providers, including CartoDB, require an API key. Pass one with + ``tiles=folium.TileLayer("CartoDB Positron", api_key="...")``. + You can also pass a custom tileset by passing a :class:`xyzservices.TileProvider` or a Leaflet-style URL to the tiles parameter: ``https://{s}.yourtiles.com/{z}/{x}/{y}.png``. @@ -175,7 +178,10 @@ class Map(JSCSSMixin, Evented): Examples -------- >>> m = folium.Map(location=[45.523, -122.675], width=750, height=500) - >>> m = folium.Map(location=[45.523, -122.675], tiles="cartodb positron") + >>> m = folium.Map( + ... location=[45.523, -122.675], + ... tiles=folium.TileLayer("cartodb positron", api_key="your-carto-key"), + ... ) >>> m = folium.Map( ... location=[45.523, -122.675], ... zoom_start=2, diff --git a/folium/plugins/dual_map.py b/folium/plugins/dual_map.py index c410aaf994..d8b7ca70bb 100644 --- a/folium/plugins/dual_map.py +++ b/folium/plugins/dual_map.py @@ -28,7 +28,7 @@ class DualMap(JSCSSMixin, MacroElement): Examples -------- >>> # DualMap accepts the same arguments as Map: - >>> m = DualMap(location=(0, 0), tiles="cartodbpositron", zoom_start=5) + >>> m = DualMap(location=(0, 0), tiles="OpenStreetMap", zoom_start=5) >>> # Add the same marker to both maps: >>> Marker((0, 0)).add_to(m) >>> # The individual maps are attributes called `m1` and `m2`: diff --git a/folium/raster_layers.py b/folium/raster_layers.py index 4b660f1ac8..f99a6d1f08 100644 --- a/folium/raster_layers.py +++ b/folium/raster_layers.py @@ -22,6 +22,29 @@ ) +def _with_api_key( + provider: xyzservices.TileProvider, api_key: str +) -> xyzservices.TileProvider: + """Return a copy of `provider` with its token placeholder set to `api_key`. + + Providers name their token field differently (``apikey``, ``accessToken``, + ``subscriptionKey``, ...). Like ``TileProvider.requires_token``, we look for + the field that holds an ``""`` placeholder and is used in + the URL. + """ + token_fields = [ + key + for key, value in provider.items() + if isinstance(value, str) and "