Skip to content
Back to top
View this page

# API reference

## Python API

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

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

  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.

  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'

  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, z int (optional)

        tile number

      scale_factor str (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_subdomain bool (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:
      url str

        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:
      name str

        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.

  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

  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}'

  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:
      keyword str (optional)

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

      name str (optional)

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

      requires_token bool (optional)

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

      function callable (optional)

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

    Returns:
      filtered Bunch

    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:
      flattened dict

        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:
      name str

        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>"
          }
       }
    }