xyzservices

library2026.3.0pypypi✓ verified 28d ago

xyzservices provides a comprehensive collection of XYZ tile providers for mapping applications, offering easy access to various base maps and overlays. It helps users integrate tile services into geospatial libraries like Folium, Leaflet, and Contextily. The current version is 2026.3.0, and it maintains a rapid release cadence, typically monthly or bi-monthly, to reflect changes in upstream tile providers.

data

pip install xyzservices

github ↗package ↗

INSTALL

IMPORT

SIG · XYZSERVICES

xyzservices

datapythonv2026.3.0

Install

1.5s avg

Import

175ms

Disk

17MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v2026.3.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.182s · 18.7MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.5s · import 0.168s · 19MB

17MB installed

● package 17MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

providers

✓ import xyzservices.providers as xyz

TileProvider

✓ from xyzservices import TileProvider

✗ from xyzservices.lib import TileProvider

TileProvider is directly exposed at the top level since 2023.x versions; avoid internal module paths.

This quickstart demonstrates how to import the providers, access a specific tile provider (CartoDB Positron), and retrieve its basic properties like URL and attribution. Some providers may require an API key, which can be formatted into the URL template.

import xyzservices.providers as xyz # Access a common, free-to-use provider provider = xyz.CartoDB.Positron print(f"Provider Name: {provider.name}") print(f"URL Template: {provider.url}") print(f"Attribution: {provider.attribution}") print(f"Minimum Zoom: {provider.min_zoom}, Maximum Zoom: {provider.max_zoom}") # Example of a provider that often requires an API key # API_KEY = os.environ.get('MAPTILER_API_KEY', '') # if API_KEY: # maptiler_provider = xyz.MapTiler.Basic.format(apiKey=API_KEY) # print(f"\nMapTiler Basic URL (with key): {maptiler_provider.url}") # else: # print("\nNote: MAPTILER_API_KEY environment variable not set. MapTiler providers often require an API key.")

Debug

Known issues

breakingStamen tile providers have been removed due to upstream deprecation. Direct usage of `xyz.Stamen.*` will fail.

fix

Migrate to `Stadia.Stamen*` variants, e.g., `xyz.Stadia.StamenToner` instead of `xyz.Stamen.Toner`.

affects: >=2023.10.1

breakingHERE API v2 has been removed, and the `HEREv3` provider has been renamed to `HERE`. Users relying on older HERE services will experience broken functionality.

fix

Update `HEREv2` usage to `xyz.HERE` and ensure you are using the v3 API schema. Refer to HERE documentation for specific parameter changes.

affects: >=2025.10.0

gotchaMany providers, particularly those from smaller or experimental services, can become broken or change URLs without notice. This can lead to `KeyError` if a provider is removed, or broken maps if the URL changes.

fix

Regularly check the `xyzservices` documentation or GitHub releases for updates on provider status. Consider using more stable, well-maintained providers for production applications. The `is_broken` attribute can be checked on providers.

affects: All versions

gotchaProviders requiring API keys (e.g., MapTiler, ThunderForest, HERE) will fail if the key is missing or incorrectly formatted. The `.format()` method is used to inject keys into the URL.

fix

Ensure you have obtained a valid API key for the respective service. Pass the key using the `.format(apiKey=YOUR_KEY)` method on the provider object before use.

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'xyzservices'

The xyzservices library is not installed in the current Python environment.

fix

pip install xyzservices

KeyError: 'SomeNonExistentProvider'

The requested tile provider name does not exist or is misspelled when accessed directly from `xyzservices.providers`.

fix

Verify the correct provider name by consulting `xyzservices.providers` documentation or listing available keys, e.g., `print(xyzservices.providers.keys())` or `xyzservices.providers.OpenStreetMap.Mapnik`.

AttributeError: 'TileProvider' object has no attribute 'get_url_template'

An attempt was made to access a non-existent attribute or method on a `TileProvider` object. The URL template is directly available as `provider.url`.

fix

Use the correct attribute for the URL template, which is `provider.url`.

ValueError: Unknown provider '...' (e.g., 'Unknown provider 'NonExistentXYZProvider'') from Contextily

When using `contextily.add_basemap`, an invalid or unrecognized string was passed as the `source` argument, which `contextily` then failed to resolve against its internal list or `xyzservices.providers`.

fix

Provide a valid provider string from `xyzservices.providers` (e.g., `'OpenStreetMap.Mapnik'`) or an `xyzservices.TileProvider` object to the `source` argument in `contextily.add_basemap()`.

Upgrade

Version history

2026.3.0latest on PyPI · released Mar 30, 2026

Audit

Dependencies

No dependency data recorded yet.

Agent activity

40 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/geopandas/xyzservices ↗

packagehttps://pypi.org/project/xyzservices/ ↗