README.md

xyzservices - Source of XYZ tiles providers

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.

Quick Start

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

Installation

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
'https://{s}.basemaps.cartocdn.com/{variant}/{z}/{x}/{y}{r}.png'

>>> 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()
True

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

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.

Contributors

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.

License

BSD 3-Clause License

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