Skip to content

TileLayer

Inherits: MapLayer

Displays square raster images in a continuous grid, sourced from the provided url_template and fallback_url.

Typically the first layer to be added to a Map, as it provides the tiles on which other layers are displayed.

Properties

Events

Properties#

additional_options class-attribute instance-attribute #

additional_options: dict[str, str] = field(
    default_factory=dict
)

Static information that should replace placeholders in the url_template. Applying API keys, for example, is a good usecase of this parameter.

Example 
TileLayer(
    url_template="https://api.tiles.mapbox.com/v4/{id}/{z}/{x}/{y}{r}.png?access_token={accessToken}",
    additional_options={
        'accessToken': '<ACCESS_TOKEN_HERE>',
        'id': 'mapbox.streets',
    },
)

display_mode class-attribute instance-attribute #

display_mode: TileDisplay = field(
    default_factory=lambda: FadeInTileDisplay()
)

Defines how tiles are displayed on the map.

enable_retina_mode class-attribute instance-attribute #

enable_retina_mode: bool = False

Whether to enable retina mode. Retina mode improves the resolution of map tiles, particularly on high density displays.

enable_tms class-attribute instance-attribute #

enable_tms: bool = False

Whether to inverse Y-axis numbering for tiles. Turn this on for TMS services.

error_image_src class-attribute instance-attribute #

error_image_src: str | None = None

The source of the tile image to show in place of the tile that failed to load.

See on_image_error property for details on the error.

evict_error_tile_strategy class-attribute instance-attribute #

evict_error_tile_strategy: (
    TileLayerEvictErrorTileStrategy | None
) = NONE

If a tile was loaded with error, the tile provider will be asked to evict the image based on this strategy.

fallback_url class-attribute instance-attribute #

fallback_url: str | None = None

Fallback URL template, used if an error occurs when fetching tiles from the url_template.

Note that specifying this (non-none) will result in tiles not being cached in memory. This is to avoid issues where the url_template is flaky, to prevent different tilesets being displayed at the same time.

It is expected that this follows the same retina support behaviour as url_template.

keep_buffer class-attribute instance-attribute #

keep_buffer: int = 2

When panning the map, keep this many rows and columns of tiles before unloading them.

max_native_zoom class-attribute instance-attribute #

max_native_zoom: int = 19

Maximum zoom number supported by the tile source has available.

Tiles from above this zoom level will not be displayed, instead tiles at this zoom level will be displayed and scaled.

Most tile servers support up to zoom level 19, which is the default. Otherwise, this should be specified.

Raises:

max_zoom class-attribute instance-attribute #

max_zoom: Number = float('inf')

The maximum zoom level up to which this layer will be displayed (inclusive). The main usage for this property is to display a different TileLayer when zoomed far in.

Prefer max_native_zoom for setting the maximum zoom level supported by the tile source.

Typically set to infinity so that there are tiles always displayed.

Raises:

min_native_zoom class-attribute instance-attribute #

min_native_zoom: int = 0

Minimum zoom level supported by the tile source.

Tiles from below this zoom level will not be displayed, instead tiles at this zoom level will be displayed and scaled.

This should usually be 0 (as default), as most tile sources will support zoom levels onwards from this.

Raises:

min_zoom class-attribute instance-attribute #

min_zoom: Number = 0.0

The minimum zoom level at which this layer is displayed (inclusive).

Typically 0.0.

Raises:

pan_buffer class-attribute instance-attribute #

pan_buffer: int = 1

When loading tiles only visible tiles are loaded by default. This option increases the loaded tiles by the given number on both axis which can help prevent the user from seeing loading tiles whilst panning. Setting the pan buffer too high can impact performance, typically this is set to 0 or 1.

subdomains class-attribute instance-attribute #

subdomains: list[str] = field(
    default_factory=lambda: ["a", "b", "c"]
)

List of subdomains used in the URL template.

For example, if subdomains is set to ["a", "b", "c"] and the url_template is "https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png", the resulting tile URLs will be:

  • "https://a.tile.openstreetmap.org/{z}/{x}/{y}.png"
  • "https://b.tile.openstreetmap.org/{z}/{x}/{y}.png"
  • "https://c.tile.openstreetmap.org/{z}/{x}/{y}.png"

tile_bounds class-attribute instance-attribute #

tile_bounds: MapLatitudeLongitudeBounds | None = None

Defines the bounds of the map. Only tiles that fall within these bounds will be loaded.

tile_size class-attribute instance-attribute #

tile_size: int = 256

The size in pixels of each tile image. Should be a positive power of 2.

Raises:

url_template instance-attribute #

url_template: str

The URL template is a string that contains placeholders, which, when filled in, create a URL/URI to a specific tile.

user_agent_package_name class-attribute instance-attribute #

user_agent_package_name: str = 'unknown'

The package name of the user agent.

zoom_offset class-attribute instance-attribute #

zoom_offset: Number = 0.0

The zoom number used in tile URLs will be offset with this value.

Raises:

zoom_reverse class-attribute instance-attribute #

zoom_reverse: bool = False

Whether the zoom number used in tile URLs will be reversed (max_zoom - zoom instead of zoom).

Events#

on_image_error class-attribute instance-attribute #

on_image_error: ControlEventHandler[TileLayer] | None = None

Fires if an error occurs when fetching the tiles.

Event handler argument data property contains information about the error.