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 "