Welcome to Mapview’s documentation!

MapView is a Kivy widget specialized into tiles-based map rendering.


MapView is based on:

Current limitations

  • The API is still moving, it may contain errors.
  • Some providers can be slow or timeout. This is not an issue from MapView.
  • If a tile is not correctly downloaded or missing from the provider, the error will be showed on the console, but nothing happen on the map itself. This can lead to a defect user experience.
  • When leaving, concurrent.futures are joining all the threads created. It can stuck the application at a maximum time of 5 seconds (requests timeout). More if the network is unstable. There is no way to force it yet.
  • The cache is not controlable, if the user move the map a lot, it can fill the disk easily. More control will be given later.


If you use Kivy garden, you can import the widget like this:

from kivy.garden.mapview import MapView, MarkerMap
map = MapView()

You can customize the default zoom and center the view on Lille by:

map = MapView(zoom=9, lon=50.6394, lat=3.057)

Then, you can create marker and place them on the map. Normally, anything that goes on a map should go on a MapLayer. Hopefully, the MapView give an API for adding marker directly, and creates a MarkerMapLayer if you did’nt created one yet:

m1 = MapMarker(lon=50.6394, lat=3.057)  # Lille
m2 = MapMarker(lon=-33.867, lat=151.206)  # Sydney

You can also change the providers by:

  1. using a provider key:

    map.map_source = "mapquest-osm"
  2. using a new MapSource object:

    source = MapSource(url="http://my-custom-map.source.com/{z}/{x}/{y}.png",
                       cache_key="my-custom-map", tile_size=512,
                       image_ext="png", attribution="@ Myself")
    map.map_source = source


class mapview.Coordinate(lon, lat)

Named tuple that represent a geographic coordinate with latitude/longitude

  • lon (float) – Longitude
  • lat (float) – Latitude
class mapview.MapSource(url, cache_key, min_zoom, max_zoom, tile_size, image_ext, attribution, subdomains)

Class that represent a map source. All the transformations from X/Y/Z to longitude, latitude, zoom, and limitations of the providers goes are stored here.

  • url (str) – Tile’s url of the providers. Defaults to http://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png
  • cache_key (str) – Key for storing the tiles. Must be unique and not colliding with another providers, otherwise tiles will not be downloaded again. Defaults to “osm”
  • min_zoom (int) – Minimum zoom value acceptable for this provider. Defaults to 0.
  • max_zoom (int) – Maximum zoom value acceptable for this provider. Defaults to 19.
  • tile_size (int) – Size of a image tile returned by the provider. Defaults to 256.
  • attribution (str) – Attribution for this provider. Defaults to empty string
  • subdomains (str) – Domains substitutions for the {s} in the url. Defaults to “abc”
get_x(zoom, lon)

Get the x position to the longitude in the map source’s projection

  • zoom (int) – Zoom level to look at
  • lon (float) – Longitude

X position

Return type:


get_y(zoom, lat)

Get the y position to the latitude in the map source’s projection

  • zoom (int) – Zoom level to look at
  • lat (float) – Latitude

Y position

Return type:


get_lon(zoom, x)

Get the longitude to the x position in the map source’s projection

  • zoom (int) – Zoom level to look at
  • x (float) – X position in the map


Return type:


get_lat(zoom, y)

Get the latitude to the y position in the map source’s projection

  • zoom (int) – Zoom level to look at
  • y (float) – Y position in the map


Return type:



Return the number of column for this provider at this zoom level.

Parameters:zoom (int) – Zoom level to look at
Returns:Number of column
Return type:int

Return the number of row for this provider at this zoom level.

Parameters:zoom (int) – Zoom level to look at
Returns:Number of rows
Return type:int

Return the maximum zoom of this source

Returns:Maximum zoom
Return type:int

Return the minimum zoom of this source

Returns:Minimum zoom
Return type:int
class mapview.MapMarker

A marker on the map, that must be used on a MapMarker, or with MapView.add_marker() or with MapView.add_widget()

Events:on_press: Fired when the MapMarker is pressed on_release: Fired when the MapMarker is release

Anchor of the Marker on the X axis. Defaults to 0.5, means the anchor will be at the X center of the image


Anchor of the marker on the Y axis. Defaults to 0, means the anchor will be at the Y bottom of the image


Latitude of the marker


Longitude of the marker


Image source of the marker, defaults to marker.png within the mapview package.

class mapview.MapView

MapView is a widget that control the map displaying, navigation and layers management.

Available events:
 on_map_relocated: called everytime the MapView change location

Longitude at the center of the widget, read-only.


Latitude at the center of the widget, read-only.


Zoom of the MapView. Must be between MapSource.get_min_zoom() and MapSource.get_max_zoom(). Default to 0


Provider of the map, default to an empty MapSource


If True, this will activate the double-tap to zoom.

Defaults to False.


Pause on any loading / tiles loading when an action is done. This allow better performance on mobile, but can be safely deactivated on desktop.

Defaults to True.


Current scale of the internal scatter, read-only. This is usually not used in user-side unless you’re hacking mapview.


When the user initiate a zoom, it will snap to the closest zoom for better graphics. The map can be blur if the map is scaled between 2 zoom.

Defaults to True, even if it doesn’t fully working yet.


Add a new layer to update at the same time than the base tile layer

Parameters:layer (MapLayer) – Map layer to add
add_marker(marker, layer=None)

Add a marker into a layer. If layer is None, it will be added in the default marker layer. If there is no default marker layer, a new one will be automatically created.

center_on(lat, lon)

Center the map on the coordinate (lat, lon)

  • lat (float) – Latitude
  • lon (float) – Longitude

Returns the bounding box from the bottom-left to the top-right.

Parameters:margin (float) – Optionnal margin to extend the Bbox bounds
Returns:Bounding box
Return type:Bbox
get_latlon_at(x, y, zoom=None):

Return the current coordinate (lat, lon) at the (x, y) widget coordinate

  • x (float) – X widget coordinate
  • y (float) – Y widget coordinate

lat/lon Coordinate

Return type:



Remove a previously added MapLayer

Parameters:layer (MapLayer) – A map layer

Remove a previously added MarkerMap

Parameters:marker (MarkerMap) – The marker
set_zoom_at(zoom, x, y, scale=None)

Sets the zoom level, leaving the (x, y) at the exact same point in the view.

  • zoom (float) – New zoom
  • x (float) – X coordinate to zoom at
  • y (float) – Y coordinate to zoom at
  • scale (float) – (internal) Scale to set on the scatter

Unload the view and all the layers. It also cancel all the remaining downloads. The map should not be used after this.

class mapview.MapLayer

A map layer. It is repositioned everytime the MapView is moved.


Function called when the MapView is moved. You must recalculate the position of your children, and handle the visibility.


Called when the view want to completely unload the layer.

class mapview.MarkerMapLayer(MapLayer)

A map layer specialized for handling MapMarker.

class mapview.mbtsource.MBTilesMapSource(MapSource)

Use a Mbtiles as a source for a MapView

class mapview.geojson.GeoJsonMapLayer(MapLayer)

A Geojson MapLayer.

Experimental, only Polygon and LineString feature are supported. Marker are not yet implemented, due to lack of API for wiring Marker selection back to you.


A Geojson filename to load, defaults to None.


A dictionary structured as a Geojson. This attribute contain the content of a source if passed.

class mapview.clustered_marker_layer.ClusteredMarkerLayer(MapLayer)

Experimental Layout that implement marker clustering. It implement its own version of Super Cluster, based itself on a KD-tree.

Aka you can load like 2000 markers without issues. The cluster index is immutable, so if you add a new marker, it will be rebuild from scratch.

Please note that the widget creation is done on the fly by the layer, not by you.

DONT use add_widget, use add_marker()


layer = ClusteredMarkerLayer()
for i in range(2000):
    lon = random() * 360 - 180
    lat = random() * 180 - 90
    layer.add_marker(lon=lon, lat=lat, cls=MapMarker)

# then you can add the layer to your mapview
mapview = MapView()

Reference to the class widget for creating a cluster widget. Defaults to ClusterMapMarker


Minimum zoom level at which clusters are generated. Defaults to 0


Maximum zoom level at which clusters are generated. Defaults to 16


Cluster radius, in pixels. Defaults to 40dp


Tile extent. Radius is calculated relative to this value. Defaults to 512.


Size of the KD-tree leaf node. Affects performance. Defaults to 64.

add_marker(lon, lat, cls=MapMarker, options=None)

Method to add a marker to the layer.

  • lon (float) – Longitude
  • lat (float) – Latitude
  • cls (object) – Widget class to use for creating this marker. Defaults to MapMarker
  • options (dict) – Options to pass to the widget at instanciation. Defaults to an empty dict.

The instance of a Marker (internal class, not the widget)

Method to call for building the cluster. It is done automatically at the first rendering. If you missed it, or need to rebuild after readding marker, just call this function.

class mapview.clustered_marker_layer.ClusterMapMarker(MapMarker)

Widget created for displaying a Cluster.


Reference to the Cluster used for this widget


Number of marker that the cluster contain.


Color used for the text, defaults to [.1, .1, .1, 1]. If you want others options, best is to do your own cluster widget including the label you want (font, size, etc) and customizing the background color.

Indices and tables