API reference

Python API

class xyzservices.TileProvider(*args, **kwargs)

A dict with attribute-access and that can be called to update keys

Examples

You can create custom TileProvider by passing your attributes to the object as it would have been a dict(). It is required to always specify name, url, and attribution.

>>> public_provider = TileProvider(
...     name="My public tiles",
...     url="https://myserver.com/tiles/{z}/{x}/{y}.png",
...     attribution="(C) xyzservices",
... )

Alternatively, you can create it from a dictionary of attributes. When specifying a placeholder for the access token, please use the "<insert your access token here>" string to ensure that requires_token() method works properly.

>>> private_provider = TileProvider(
...    {
...        "url": "https://myserver.com/tiles/{z}/{x}/{y}.png?apikey={accessToken}",
...        "attribution": "(C) xyzservices",
...        "accessToken": "<insert your access token here>",
...        "name": "my_private_provider",
...    }
... )

It is customary to include html_attribution attribute containing HTML string as '&copy; <a href="https://www.openstreetmap.org/copyright">OpenStreetMap</a> contributors' alongisde a plain-text attribution.

You can then fetch all information as attributes:

>>> public_provider.url
'https://myserver.com/tiles/{z}/{x}/{y}.png'

>>> public_provider.attribution
'(C) xyzservices'

To ensure you will be able to use the tiles, you can check if the TileProvider requires a token or API key.

>>> public_provider.requires_token()
False
>>> private_provider.requires_token()
True

You can also generate URL in the required format with or without placeholders:

>>> public_provider.build_url()
'https://myserver.com/tiles/{z}/{x}/{y}.png'
>>> private_provider.build_url(x=12, y=21, z=11, accessToken="my_token")
'https://myserver.com/tiles/11/12/21.png?access_token=my_token'

Methods

build_url([x, y, z, scale_factor, ...])	Build the URL of tiles from the TileProvider object
from_qms(name)	Creates a TileProvider object based on the definition from the Quick Map Services open catalog.
requires_token()	Returns True if the TileProvider requires access token to fetch tiles.

build_url(x: int | str | None = None, y: int | str | None = None, z: int | str | None = None, scale_factor: str | None = None, fill_subdomain: bool | None = True, **kwargs) → str

Build the URL of tiles from the TileProvider object

Can return URL with placeholders or the final tile URL.

Parameters:

x, y, zint (optional)

tile number

scale_factorstr (optional)

Scale factor (where supported). For example, you can get double resolution (512 x 512) instead of standard one (256 x 256) with "@2x". If you want to keep a placeholder, pass “{r}”.

fill_subdomainbool (optional, default True)

Fill subdomain placeholder with the first available subdomain. If False, the URL will contain {s} placeholder for subdomain.

**kwargs

Other potential attributes updating the TileProvider.

Returns:

urlstr

Formatted URL

Examples

>>> import xyzservices.providers as xyz

>>> xyz.CartoDB.DarkMatter.build_url()
'https://a.basemaps.cartocdn.com/dark_all/{z}/{x}/{y}.png'

>>> xyz.CartoDB.DarkMatter.build_url(x=9, y=11, z=5)
'https://a.basemaps.cartocdn.com/dark_all/5/9/11.png'

>>> xyz.CartoDB.DarkMatter.build_url(x=9, y=11, z=5, scale_factor="@2x")
'https://a.basemaps.cartocdn.com/dark_all/5/9/11@2x.png'

>>> xyz.MapBox.build_url(accessToken="my_token")
'https://api.mapbox.com/styles/v1/mapbox/streets-v11/tiles/{z}/{x}/{y}?access_token=my_token'

classmethod from_qms(name: str) → TileProvider

Creates a TileProvider object based on the definition from the Quick Map Services open catalog.

Parameters:

namestr

Service name

Returns:

TileProvider

Examples

>>> from xyzservices.lib import TileProvider
>>> provider = TileProvider.from_qms("OpenTopoMap")

requires_token() → bool

Returns True if the TileProvider requires access token to fetch tiles.

The token attribute name vary and some TileProvider objects may require more than one token (e.g. HERE). The information is deduced from the presence of ‘<insert your…’ string in one or more of attributes. When specifying a placeholder for the access token, please use the "<insert your access token here>" string to ensure that requires_token() method works properly.

Returns:

bool

Examples

>>> import xyzservices.providers as xyz
>>> xyz.MapBox.requires_token()
True

>>> xyz.CartoDB.Positron
False

We can specify this API key by calling the object or overriding the attribute. Overriding the attribute will alter existing object:

>>> xyz.OpenWeatherMap.Clouds["apiKey"] = "my-private-api-key"

Calling the object will return a copy:

>>> xyz.OpenWeatherMap.Clouds(apiKey="my-private-api-key")

class xyzservices.Bunch

A dict with attribute-access

Bunch is used to store TileProvider objects.

Examples

>>> black_and_white = TileProvider(
...     name="My black and white tiles",
...     url="https://myserver.com/bw/{z}/{x}/{y}",
...     attribution="(C) xyzservices",
... )
>>> colorful = TileProvider(
...     name="My colorful tiles",
...     url="https://myserver.com/color/{z}/{x}/{y}",
...     attribution="(C) xyzservices",
... )
>>> MyTiles = Bunch(BlackAndWhite=black_and_white, Colorful=colorful)
>>> MyTiles
{'BlackAndWhite': {'name': 'My black and white tiles', 'url': 'https://myserver.com/bw/{z}/{x}/{y}', 'attribution': '(C) xyzservices'}, 'Colorful': {'name': 'My colorful tiles', 'url': 'https://myserver.com/color/{z}/{x}/{y}', 'attribution': '(C) xyzservices'}}
>>> MyTiles.BlackAndWhite.url
'https://myserver.com/bw/{z}/{x}/{y}'

Methods

filter([keyword, name, requires_token, function])	Return a subset of the Bunch matching the filter conditions
flatten()	Return the nested Bunch collapsed into the one level dictionary.
query_name(name)	Return TileProvider based on the name query

filter(keyword: str | None = None, name: str | None = None, requires_token: bool | None = None, function: Callable[[TileProvider], bool] = None) → Bunch

Return a subset of the Bunch matching the filter conditions

Each TileProvider within a Bunch is checked against one or more specified conditions and kept if they are satisfied or removed if at least one condition is not met.

Parameters:

keywordstr (optional)

Condition returns True if keyword string is present in any string value in a TileProvider object. The comparison is not case sensitive.

namestr (optional)

Condition returns True if name string is present in the name attribute of TileProvider object. The comparison is not case sensitive.

requires_tokenbool (optional)

Condition returns True if TileProvider.requires_token() returns True (i.e. if the object requires specification of API token).

functioncallable (optional)

Custom function taking TileProvider as an argument and returns bool. If function is given, other parameters are ignored.

Returns:

filteredBunch

Examples

>>> import xyzservices.providers as xyz

You can filter all free providers (not requiring API token):

>>> free_providers = xyz.filter(requires_token=False)

Or all providers with open in the name:

>>> open_providers = xyz.filter(name="open")

You can use keyword search to find all providers based on OpenStreetMap data:

>>> osm_providers = xyz.filter(keyword="openstreetmap")

You can combine multiple conditions to find providers based on OpenStreetMap data that require API token:

>>> osm_locked = xyz.filter(keyword="openstreetmap", requires_token=True)

You can also pass custom function that takes TileProvider and returns boolean value. You can then find all providers with max_zoom smaller than 18:

>>> def zoom18(provider):
...    if hasattr(provider, "max_zoom") and provider.max_zoom < 18:
...        return True
...    return False
>>> small_zoom = xyz.filter(function=zoom18)

flatten() → dict

Return the nested Bunch collapsed into the one level dictionary.

Dictionary keys are TileProvider names (e.g. OpenStreetMap.Mapnik) and its values are TileProvider objects.

Returns:

flatteneddict

dictionary of TileProvider objects

Examples

>>> import xyzservices.providers as xyz
>>> len(xyz)
36

>>> flat = xyz.flatten()
>>> len(xyz)
207

query_name(name: str) → TileProvider

Return TileProvider based on the name query

Returns a matching TileProvider from the Bunch if the name contains the same letters in the same order as the provider’s name irrespective of the letter case, spaces, dashes and other characters. See examples for details.

Parameters:

namestr

Name of the tile provider. Formatting does not matter.

Returns:

match: TileProvider

Examples

>>> import xyzservices.providers as xyz

All these queries return the same CartoDB.Positron TileProvider:

>>> xyz.query_name("CartoDB Positron")
>>> xyz.query_name("cartodbpositron")
>>> xyz.query_name("cartodb-positron")
>>> xyz.query_name("carto db/positron")
>>> xyz.query_name("CARTO_DB_POSITRON")
>>> xyz.query_name("CartoDB.Positron")

Providers JSON

After the installation, you will find the JSON used as a database of providers in share/xyzservices/providers.json if you want to use it outside of a Python ecosystem. The JSON is structured along the following model example:

{
   "single_provider_name": {
      "url": "https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png",
      "max_zoom": 19,
      "attribution": "(C) OpenStreetMap contributors",
      "html_attribution": "&copy; <a href=\"https://www.openstreetmap.org/copyright\">OpenStreetMap</a> contributors",
      "name": "OpenStreetMap.Mapnik"
   },
   "provider_bunch_name": {
      "first_provider_name": {
            "url": "https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png",
            "max_zoom": 19,
            "attribution": "(C) OpenStreetMap contributors",
            "html_attribution": "&copy; <a href=\"https://www.openstreetmap.org/copyright\">OpenStreetMap</a> contributors",
            "name": "OpenStreetMap.Mapnik"
      },
      "second_provider_name": {
            "url": "https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png?access-token={accessToken}",
            "max_zoom": 19,
            "attribution": "(C) OpenStreetMap contributors",
            "html_attribution": "&copy; <a href=\"https://www.openstreetmap.org/copyright\">OpenStreetMap</a> contributors",
            "name": "OpenStreetMap.Mapnik",
            "accessToken": "<insert your access token here>"
      }
   }
}