Skip to content

Add api_key option to TileLayer for providers that need a key - #2361

Open
nilay-v3rma wants to merge 1 commit into
python-visualization:mainfrom
nilay-v3rma:tilelayer-api-key
Open

nilay-v3rma wants to merge 1 commit into
python-visualization:mainfrom
nilay-v3rma:tilelayer-api-key

Conversation

@nilay-v3rma

Copy link
Copy Markdown

Addresses part of #2321 (item 3, plus the docstrings from item 2).

Since CARTO started requiring an API key, folium.TileLayer("CartoDB Positron") always renders "API KEY REQUIRED" tiles. You can't pass a key with a built-in name: xyzservices removes the ?key={apikey} placeholder before folium gets the URL. Passing apikey="..." doesn't help either. It lands in the Leaflet options and is ignored without any error.

Change

TileLayer gets an api_key argument:

folium.TileLayer("CartoDB Positron", api_key="my-key").add_to(m)
folium.Map(tiles=folium.TileLayer("cartodb voyager", api_key="my-key"))
  • It fills in the provider's token placeholder, whatever the provider calls it. In xyzservices that can be apikey, apiKey, key, accessToken or subscriptionKey, so the same argument also works for Thunderforest, MapBox, Stadia and others. The placeholder is found with the rule TileProvider.requires_token() uses: a field containing "<insert your" that appears in the URL. No provider has more than one such field.
  • It raises ValueError when given with a custom URL, or with a provider that has nothing to fill (no key needed, or a key is already set). Before this change the key was dropped without any error.
  • The provider passed in isn't modified. A copy is made with provider(**{field: key}).

Docstrings: TileLayer now says CartoDB needs a key and documents api_key. The Map docstring explains how to pass a key, and its example uses one. The DualMap example now uses OpenStreetMap.

Not in this PR

  • Map itself doesn't get an api_key argument. Map forwards only a few tile options, and tiles=TileLayer(...) is already how you pass anything more. I can add Map(..., api_key=...) if you'd like.
  • The docs pages from item 1. The issue author mentioned they have local changes for those.
  • No changes to the xyzservices warning text (item 4). The warning already links the key registration page.

Tests

New tests in tests/test_raster_layers.py check that:

  • the key ends up in the URL, both from a name and from a TileProvider
  • no warning is raised when a key is given
  • a non-apikey placeholder (MapBox's accessToken) is filled
  • the original provider is not modified
  • a custom URL and a provider without a placeholder are rejected

pre-commit and mypy pass on the changed files.

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 python-visualization#2321

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant