Skip to content
Back to top
View this page

# 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

Important

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.

## 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)