xyzservices

The xyzservices Gallery allows you to visually browse and preview the available XYZ tile providers.

Important Considerations:

• API Keys: Some providers require an API key. You must provide your own key and use the validate button in the gallery interface to load the tiles.
• Domain Whitelisting: Certain providers (such as Stadia) may require you to whitelist your domain in their respective service settings before tiles will load correctly.

You can install xyzservices using either pip or conda. The package has no external dependencies other than Python built-ins.

conda install xyzservices -c conda-forge

pip install xyzservices

A TileProvider object is a dictionary-like object (with attribute access) that contains the configuration for an XYZ tile service.

Key characteristics:

• Required fields: It must contain a url string with {z}/{x}/{y} placeholders.
• Optional metadata: It may include attribution (text for plots), max_zoom (maximum available zoom level), name, and html_attribution.
• Hierarchical structure: Many providers are organized into groups. For example, xyz.OpenStreetMap is a group, and xyz.OpenStreetMap.Mapnik is a specific TileProvider instance.
• Status check: If a provider is non-functional, it may have a status attribute set to "broken".

import xyzservices.providers as xyz

# Accessing a specific provider
provider = xyz.OpenStreetMap.Mapnik
print(type(provider))  # <class 'xyzservices.providers.TileProvider'>
print(provider['url'])

Stadia Maps can be used by whitelisting your domain in your account settings. Alternatively, you can use an API token by manually appending an api_key placeholder to the provider's URL.

provider = xyz.Stadia.AlidadeSmooth(api_key="<insert api_key here>")
provider["url"] = provider["url"] + "?api_key={api_key}"  # adding API key placeholder

Register at Mapbox to get a map_ID (e.g., "mapbox/satellite-v9") and an accessToken. Pass these to the MapBox provider.

xyz.MapBox(id="<insert map_ID here>", accessToken="my-private-ACCESS_TOKEN")

For HEREv3 layers, register at the HERE developer portal to obtain an apiKey. You can provide the key in two ways:

1. Modify the existing object: Overriding the attribute will alter the existing object in the xyz module.
2. Call the object: Calling the object as a function returns a copy with the key applied, leaving the original object unchanged.

For legacy projects, you can use app_id and app_code instead.

# Overriding the attribute will alter the existing object
xyz.HEREv3.terrainDay["apiKey"] = "my-private-api-key"

# Calling the object will return a copy
xyz.HEREv3.terrainDay(apiKey="my-private-api-key")

# Legacy projects
xyz.HERE.terrainDay(app_id="my-private-app-id", app_code="my-app-code")

The TileProvider class is the primary interface for interacting with XYZ tile providers. It provides methods to construct tile URLs and manage authentication requirements.

Key methods:

• build_url(...): Generates a tile URL based on the provider's template.
• requires_token(): Indicates if the provider requires an access token.
• from_qms(...): Creates a provider from QMS (QuickMapServices) data.

from xyzservices import TileProvider
# Usage depends on specific implementation details of build_url and from_qms

Register at MapTiler Cloud and retrieve your API key from Account/Keys. Pass this key to the key parameter of the provider.

xyz.MapTiler.Streets(key="<insert key here>")

The Bunch class is used to manage collections of providers (provider bunches). It provides utility methods for navigating and filtering provider data.

Key methods:

• filter(...): Filters the collection of providers.
• flatten(): Flattens the provider structure.
• query_name(...): Queries providers by name.

Register at Thunderforest to obtain an api_key. Pass it to the apikey parameter of the provider.

xyz.Thunderforest.Landscape(apikey="<insert api_key here>")

The xyzservices.providers module (commonly imported as xyz) acts as a Bunch (an enhanced dictionary) containing all available XYZ tile sources.

In interactive environments like Jupyter, xyz provides a collapsible inventory of providers. You can explore available providers using xyz.keys().

Accessing a specific provider returns a TileProvider object containing metadata such as the tile URL and attribution.

import xyzservices.providers as xyz

# Access provider details
print(xyz.OpenStreetMap.Mapnik.url)
print(xyz.OpenStreetMap.Mapnik.attribution)

Register at Jawg.io to obtain an access token. You can access default maps or your own customized maps by specifying the accessToken and an optional variant (the map ID).

xyz.Jawg.Streets(
    accessToken="<insert access token here>",
    variant="<insert map id here or blank for default variant>"
)