Source of XYZ tiles providers.

Illustrative tiles. (C) OpenStreetMap, (C) OpenMapTIles, (C) Stadia Maps, (C) OpenTopoMap,  (C) Thunderforest, (C) JawgMaps, (C) Stamen Design, (C) Esri -- Source: Esri, i-cubed, USDA, USGS, AEX, GeoEye, Getmapping, Aerogrid, IGN, IGP, UPR-EGP, and the GIS User Community

xyzservices is a lightweight library providing a repository of available XYZ services offering raster basemap tiles. The repository is provided via Python API and as a compressed JSON file.

XYZ tiles can be used as background for your maps to provide necessary spatial context. xyzservices offer specifications of many tile services and provide an easy-to-use tools to plug them into your work, no matter if interactive or static.

Tests codecov

Quick Start#

Using xyzservices is simple and in most cases does not involve more than a line of code.


You can install xyzservices from conda or pip:

conda install xyzservices -c conda-forge
pip install xyzservices

The package does not depend on any other apart from those built-in in Python.

Providers API#

The key part of xyzservices are providers:

>>> import xyzservices.providers as xyz

xyzservices.providers or just xyz for short is a Bunch of providers, an enhanced dict. If you are in Jupyter-like environment, xyz will offer collapsible inventory of available XYZ tile sources. You can also explore it as a standard dict using xyz.keys(). Once you have picked your provider, you get its details as a TileProvider object with all the details you may need:

>>> xyz.CartoDB.Positron.url

>>> xyz.CartoDB.Positron.attribution
'(C) OpenStreetMap contributors (C) CARTO'

You can also check if the TileProvider needs API token and pass it to the object if needed.

>>> xyz.MapBox.requires_token()

>>> xyz.MapBox["accessToken"] = "my_personal_token"
>>> xyz.MapBox.requires_token()


You should always check the license and terms and conditions of XYZ tiles you want to use. Not all of them can be used in all circumstances.

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.


xyzservices is developed by a community of enthusiastic volunteers and lives under geopandas GitHub organization. You can see a full list of contributors here.

The main group of providers is retrieved from the leaflet-providers project that contains both openly accessible providers as well as those requiring registration. All of them are considered free.

If you would like to contribute to the project, have a look at the list of open issues, particularly those labeled as good first issue.


BSD 3-Clause License

Resources coming from the leaflet-providers project are licensed under BSD 2-Clause License (© 2013 Leaflet Providers)