XYZ Services Tiles Providers

2026.3.0 · active · verified Thu Apr 09

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.

Warnings

breaking Stamen 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`.
breaking HERE 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.
gotcha Many 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.
gotcha Providers 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.

Install

pip install xyzservices Install xyzservices

Imports

providers
```
import xyzservices.providers as xyz
```
TileProvider
```
from xyzservices import TileProvider
```
TileProvider is directly exposed at the top level since 2023.x versions; avoid internal module paths.

Quickstart

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.")

view raw JSON →