# API documentation¶

## Figures and layers¶

gmaps.figure(display_toolbar=True, display_errors=True, zoom_level=None, center=None)

Create a gmaps figure

This returns a Figure object to which you can add data layers.

Parameters: display_toolbar (boolean, optional) – Boolean denoting whether to show the toolbar. Defaults to True. display_errors (boolean, optional) – Boolean denoting whether to show errors that arise in the client. Defaults to True. zoom_level (int, optional) – Integer between 0 and 21 indicating the initial zoom level. High values are more zoomed in. By default, the zoom level is chosen to fit the data passed to the map. If specified, you must also specify the map center. center (tuple, optional) – Latitude-longitude pair determining the map center. By default, the map center is chosen to fit the data passed to the map. If specified, you must also specify the zoom level. A gmaps.Figure widget.
>>> import gmaps
>>> gmaps.configure(api_key="AI...")
>>> fig = gmaps.figure()
>>> locations = [(46.1, 5.2), (46.2, 5.3), (46.3, 5.4)]


You can also explicitly specify the intiial map center and zoom:

>>> fig = gmaps.figure(center=(46.0, -5.0), zoom_level=8)

gmaps.heatmap_layer(locations, weights=None, max_intensity=None, dissipating=True, point_radius=None, opacity=0.6, gradient=None)

Create a heatmap layer.

This returns a gmaps.Heatmap or a gmaps.WeightedHeatmap object that can be added to a gmaps.Figure to draw a heatmap. A heatmap shows the density of points in or near a particular area.

To set the parameters, pass them to the constructor or set them on the Heatmap object after construction:

>>> heatmap = gmaps.heatmap_layer(locations, max_intensity=10)


or:

>>> heatmap = gmaps.heatmap_layer(locations)
>>> heatmap.max_intensity = 10

>>> fig = gmaps.figure()
>>> locations = [(46.1, 5.2), (46.2, 5.3), (46.3, 5.4)]
>>> heatmap = gmaps.heatmap_layer(locations)
>>> heatmap.max_intensity = 2

gmaps.symbol_layer(locations, hover_text='', fill_color=None, fill_opacity=1.0, stroke_color=None, stroke_opacity=1.0, scale=3, info_box_content=None, display_info_box=None)

Symbol layer

Add this layer to a gmaps.Figure instance to draw symbols on the map. A symbol will be drawn on the map for each point in the locations argument.

>>> fig = gmaps.figure()
>>> locations = [
(-34.0, -59.166672),
(-32.23333, -64.433327),
(40.166672, 44.133331),
(51.216671, 5.0833302),
(51.333328, 4.25)
]
>>> symbols = gmaps.symbol_layer(
locations, fill_color="red", stroke_color="red")


You can set a list of information boxes, which will be displayed when the user clicks on a marker.

>>> list_of_infoboxes = [
"Simple string info box",
"<a href='http://example.com'>HTML content</a>"
]
>>> symbol_layer = gmaps.symbol_layer(
locations, info_box_content=list_of_infoboxes)


You can also set text that appears when someone’s mouse hovers over a point:

>>> names = ["Atucha", "Embalse", "Armenia", "BR", "Doel"]
>>> symbol_layer = gmaps.symbol_layer(locations, hover_text=names)


Apart from locations, which must be an iterable of (latitude, longitude) pairs, the arguments can be given as either a list of the same length as locations, or a single value. If given as a single value, this value will be broadcast to every marker. Thus, these two calls are equivalent:

>>> symbols = gmaps.symbol_layer(
locations, fill_color=["red"]*len(locations))
>>> symbols = gmaps.symbol_layer(
locations, fill_color="red")


The former is useful for passing different colours to different symbols.

>>> colors = ["red", "green", "blue", "black", "white"]
>>> symbols = gmaps.symbol_layer(
locations, fill_color=colors, stroke_color=colors)

Parameters: locations (list of tuples) – List of (latitude, longitude) pairs denoting a single point. Latitudes are expressed as a float between -90 (corresponding to 90 degrees south) and +90 (corresponding to 90 degrees north). Longitudes are expressed as a float between -180 (corresponding to 180 degrees west) and +180 (corresponding to 180 degrees east). hover_text (string or list of strings, optional) – Text to be displayed when a user’s mouse is hovering over a marker. This can be either a single string, in which case it will be applied to every marker, or a list of strings, in which case it must be of the same length as locations. If this is set to an empty string, nothing will appear when the user’s mouse hovers over a symbol. fill_color (single color or list of colors, optional) – The fill color of the symbol. This can be specified as a single color, in which case the same color will apply to every symbol, or as a list of colors, in which case it must be the same length as locations. Colors can be specified as a simple string, e.g. ‘blue’, as an RGB tuple, e.g. (100, 0, 0), or as an RGBA tuple, e.g. (100, 0, 0, 0.5). fill_opacity (float or list of floats, optional) – The opacity of the fill color. The opacity should be a float between 0.0 (transparent) and 1.0 (opaque), or a list of floats. 1.0 by default. stroke_color (single color or list of colors, optional) – The stroke color of the symbol. This can be specified as a single color, in which case the same color will apply to every symbol, or as a list of colors, in which case it must be the same length as locations. Colors can be specified as a simple string, e.g. ‘blue’, as an RGB tuple, e.g. (100, 0, 0), or as an RGBA tuple, e.g. (100, 0, 0, 0.5). stroke_opacity (float or list of floats, optional) – The opacity of the stroke color. The opacity should be a float between 0.0 (transparent) and 1.0 (opaque), or a list of floats. 1.0 by default. scale (integer or list of integers, optional) – How large the marker is. This can either be a single integer, in which case the same scale will be applied to every marker, or it must be an iterable of the same length as locations. The scale must be greater than 1. This defaults to 3. info_box_content (string or list of strings, optional) – Content to be displayed when user clicks on a marker. This should either be a single string, in which case the same content will apply to every marker, or a list of strings of the same length of the locations list. display_info_box (boolean or list of booleans, optional) – Whether to display an info box when the user clicks on a symbol. This should either be a single boolean value, in which case it will be applied to every symbol, or a list of boolean values of the same length as the locations list. The default value is True for any symbols for which info_box_content is set, and False otherwise.
gmaps.marker_layer(locations, hover_text='', label='', info_box_content=None, display_info_box=None)

Marker layer

Add this layer to a gmaps.Figure instance to draw markers corresponding to specific locations on the map. A marker will be drawn on the map for each point in the locations argument.

>>> fig = gmaps.figure()
>>> locations = [
(-34.0, -59.166672),
(-32.23333, -64.433327),
(40.166672, 44.133331),
(51.216671, 5.0833302),
(51.333328, 4.25)
]
>>> markers = gmaps.marker_layer(locations)

Parameters: locations (list of tuples) – List of (latitude, longitude) pairs denoting a single point. Latitudes are expressed as a float between -90 (corresponding to 90 degrees south) and +90 (corresponding to 90 degrees north). Longitudes are expressed as a float between -180 (corresponding to 180 degrees west) and +180 (corresponding to 180 degrees east). hover_text (string or list of strings, optional) – Text to be displayed when a user’s mouse is hovering over a marker. This can be either a single string, in which case it will be applied to every marker, or a list of strings, in which case it must be of the same length as locations. If this is set to an empty string, nothing will appear when the user’s mouse hovers over a marker. label (string or list of strings, optional) – Text to be displayed inside the marker. Google maps only displays the first letter of whatever string is passed to the marker. This can be either a single string, in which case every marker will receive the same label, or a list of strings, in which case it must be of the same length as locations. info_box_content (string or list of strings, optional) – Content to be displayed when user clicks on a marker. This should either be a single string, in which case the same content will apply to every marker, or a list of strings of the same length of the locations list. display_info_box (boolean or list of booleans, optional) – Whether to display an info box when the user clicks on a marker. This should either be a single boolean value, in which case it will be applied to every marker, or a list of boolean values of the same length as the locations list. The default value is True for any markers for which info_box_content is set, and False otherwise.
gmaps.geojson_layer(geojson, fill_color=None, fill_opacity=0.4, stroke_color=None, stroke_opacity=0.8, stroke_weight=1.0)

GeoJSON layer

Add this layer to a gmaps.Figure instance to render GeoJSON.

Let’s start by fetching some GeoJSON. We could have loaded it from file, but let’s load it from a URL instead. You will need requests.

>>> import json
>>> import requests
>>> countries_string = requests.get(
"https://raw.githubusercontent.com/johan/world.geo.json/master/countries.geo.json"
).content

>>> import gmaps
>>> gmaps.configure(api_key="AI...")
>>> fig = gmaps.figure()
>>> geojson = gmaps.geojson_layer(countries)
>>> fig


We can pass style options into the layer. Let’s assign a random color to each country:

>>> import random
>>> colors = [
random.choice(['red', 'green', 'blue', 'purple', 'yellow', 'teal'])
for country in countries['features']
]
>>> geojson = gmaps.geojson_layer(countries, fill_color=colors)


Finally, let’s also make our colors more transparent and decrease the stroke weight.

>>> geojson = gmaps.geojson_layer(
countries, fill_color=colors, fill_opacity=0.2, stroke_weight=1)

Parameters: geojson (dict) – A Python dictionary containing a GeoJSON feature collection. If you have a GeoJSON file, you will need to load it using json.load. fill_color (single color or list of colors, optional) – The fill color of the symbol. This can be specified as a single color, in which case the same color will apply to every symbol, or as a list of colors, in which case it must be the same length as locations. Colors can be specified as a simple string, e.g. ‘blue’, as an RGB tuple, e.g. (100, 0, 0), or as an RGBA tuple, e.g. (100, 0, 0, 0.5). fill_opacity (float or list of floats, optional) – The opacity of the fill color. The opacity should be a float between 0.0 (transparent) and 1.0 (opaque), or a list of floats. 0.4 by default. stroke_color (single color or list of colors, optional) – The stroke color of the symbol. This can be specified as a single color, in which case the same color will apply to every symbol, or as a list of colors, in which case it must be the same length as locations. Colors can be specified as a simple string, e.g. ‘blue’, as an RGB tuple, e.g. (100, 0, 0), or as an RGBA tuple, e.g. (100, 0, 0, 0.5). stroke_opacity (float or list of floats, optional) – The opacity of the stroke color. The opacity should be a float between 0.0 (transparent) and 1.0 (opaque), or a list of floats. 0.8 by default. stroke_weight (float or list of floats, optional) – The width, in pixels, of the stroke. Useful values range from 0.0 (corresponding to no stroke) to about 20, corresponding to a very fat brush. 3.0 by default.
gmaps.directions_layer(start, end, waypoints=None, avoid_ferries=False, travel_mode='DRIVING', avoid_highways=False, avoid_tolls=False, optimize_waypoints=False)

Create a directions layer.

Add this layer to a gmaps.Figure instance to draw directions on the map.

>>> fig = gmaps.figure()
>>> start = (46.2, 6.1)
>>> end = (47.4, 8.5)
>>> directions = gmaps.directions_layer(start, end)
>>> fig


You can also add waypoints on the route:

>>> waypoints = [(46.4, 6.9), (46.9, 8.0)]
>>> directions = gmaps.directions_layer(start, end, waypoints=waypoints)


You can choose the travel mode:

>>> directions = gmaps.directions_layer(start, end, travel_mode='WALKING')

Parameters: start (2-element tuple) – (Latitude, longitude) pair denoting the start of the journey. end (2-element tuple) – (Latitude, longitude) pair denoting the end of the journey. waypoints (List of 2-element tuples, optional) – Iterable of (latitude, longitude) pair denoting waypoints. Google maps imposes a limitation on the total number of waypoints. This limit is currently 23. You cannot use waypoints when the travel_mode is 'TRANSIT'. travel_mode (str, optional) – Choose the mode of transport. One of 'BICYCLING', 'DRIVING', 'WALKING' or 'TRANSIT'. A travel mode of 'TRANSIT' indicates public transportation. Defaults to 'DRIVING'. avoid_ferries (bool, optional) – Avoid ferries where possible. avoid_highways (bool, optional) – Avoid highways where possible. avoid_tolls (bool, optional) – Avoid toll roads where possible. optimize_waypoints (bool, optional) – If set to true, will attempt to re-order the supplied intermediate waypoints to minimize overall cost of the route.
gmaps.bicycling_layer()

Bicycling layer.

Adds cycle routes and decreases the weight of main routes on the map.

Returns: A gmaps.Bicycling widget.
>>> fig = gmaps.figure()

gmaps.transit_layer()

Transit layer.

Adds information about public transport lines to the map. This only affects region for which Google has public transport information.

Returns: A gmaps.Transit widget.
# map centered on London
>>> fig = gmaps.figure(center=(51.5, -0.2), zoom_level=11)
>>> fig

gmaps.traffic_layer(auto_refresh=True)

Traffic layer.

Adds information about the current state of traffic to the map. This layer only works at sufficiently high zoom levels, and for regions for which Google Maps has traffic information.

Parameters: auto_refresh (bool, optional) – Whether the traffic layer refreshes with updated information automatically. This is true by default. A gmaps.Traffic widget.
# map centered on London
>>> fig = gmaps.figure(center=(51.5, -0.2), zoom_level=11)
>>> fig


## Utility functions¶

gmaps.configure(api_key=None)

Parameters: api_key – String denoting the key to use when accessing Google maps, or None to not pass an API key.
gmaps.locations.locations_to_list(locations)

Convert from a generic iterable of locations to a list of tuples

Layer widgets only accepts lists of tuples, but we want the user to be able to pass in any reasonable iterable. We therefore need to convert the iterable passed in.

## Low level widgets¶

class gmaps.Figure(**kwargs)

Figure widget

This is the base widget for a Figure. Prefer instantiating instances of Figure using the gmaps.figure() factory method.

add_layer(layer)

Add a data layer to this figure.

Parameters: layer – a gmaps layer.
>>> f = figure()


layer creation functions

gmaps.heatmap_layer()
Create a heatmap layer
gmaps.symbol_layer()
Create a layer of symbols
gmaps.marker_layer()
Create a layer of markers
gmaps.geojson_layer()
Create a GeoJSON layer
gmaps.directions_layer()
Create a layer with directions
gmaps.bicycling_layer()
Create a layer showing cycle routes
gmaps.transit_layer()
Create a layer showing public transport
gmaps.traffic_layer()
Create a layer showing current traffic information
class gmaps.Map(**kwargs)

Base map class

Instances of this act as a base map on which you can add additional layers.

You should use the gmaps.figure() factory method to instiate a figure, rather than building this class directly.

Parameters: initial_viewport – Define the initial zoom level and map centre. You should construct this using one of the static methods on gmaps.InitialViewport. By default, the map is centered on the data.
>>> m = gmaps.figure()


To explicitly set the initial map zoom and center:

>>> zoom_level = 8
>>> center = (20.0, -10.0)
>>> viewport = InitialViewport.from_zoom_center(zoom_level, center)
>>> m = gmaps.figure(initial_viewport=viewport)

class gmaps.InitialViewport(**metadata)

Traitlet defining the initial viewport for a map.

static from_data_bounds()

Create a viewport centered on the map’s data.

Most of the time, you should rely on the defaults provided by the gmaps.figure() factory method, rather than creating a viewport yourself.

>>> m = gmaps.Map(initial_viewport=InitialViewport.from_data_bounds())

static from_zoom_center(zoom_level, center)

Create a viewport by explicitly setting the zoom and center

Most of the time, you should rely on the defaults provided by the gmaps.figure() factory method, rather than creating a viewport yourself.

Parameters: zoom_level (int) – The zoom level for the map. A value between 0 (zoomed out) and 21 (zoomed in). Note that the highest zoom levels are only available in some regions of the world (e.g. cities). center (tuple of floats) – (Latitude, longitude) pair denoting the map center.
>>> zoom_level = 8
>>> center = (20.0, -10.0)
>>> viewport = InitialViewport.from_zoom_center(zoom_level, center)
>>> m = gmaps.figure(initial_viewport=viewport)

class gmaps.Heatmap(**kwargs)

Heatmap layer.

Add this to a Map instance to draw a heatmap. A heatmap shows the density of points in or near a particular area.

You should not instantiate this directly. Instead, use the gmaps.heatmap_layer() factory function.

>>> fig = gmaps.figure()
>>> locations = [(46.1, 5.2), (46.2, 5.3), (46.3, 5.4)]
>>> heatmap = gmaps.heatmap_layer(locations)
>>> heatmap.max_intensity = 2

class gmaps.WeightedHeatmap(**kwargs)

Heatmap with weighted points.

Add this layer to a Map instance to draw a heatmap. Unlike the plain Heatmap layer, which assumes that all points should have equal weight, this layer lets you specifiy different weights for points.

You should not instantiate this directly. Instead, use the gmaps.heatmap_layer() factory function, passing in a parameter for weights.

>>> fig = gmaps.figure()
>>> locations = [(46.1, 5.2), (46.2, 5.3), (46.3, 5.4)]
>>> weights = [0.5, 0.2, 0.8]
>>> heatmap = gmaps.heatmap_layer(locations, weights=weights)
>>> heatmap.max_intensity = 2

class gmaps.Symbol(**kwargs)

Class representing a single symbol.

Symbols are like markers, but the point is represented by an SVG symbol, rather than the default inverted droplet. Symbols should be added to the map via the ‘Symbols’ widget.

class gmaps.Marker(**kwargs)

Class representing a marker.

Markers should be added to the map via the ‘Markers’ widget.

class gmaps.Markers(**kwargs)

A collection of markers or symbols.

class gmaps.GeoJsonFeature(**kwargs)

Widget for a single GeoJSON feature.

Prefer to use the geojson_layer function to construct these, rather than making them explicitly.

class gmaps.GeoJson(**kwargs)

Widget for a collection of GeoJSON features.

Prefer to use the geojson_layer function to construct this, rather than making them explicitly.

Use the features attribute on this class to change the style of the features in this layer.

class gmaps.Directions(**kwargs)

Directions layer.

Add this to a gmaps.Figure instance to draw directions.

Use the gmaps.directions_layer() factory function to instantiate this class, rather than the constructor.

>>> fig = gmaps.figure()
>>> start = (46.2, 6.1)
>>> end = (47.4, 8.5)
>>> waypoints = [(52.37403, 4.88969)]
>>> directions_layer = gmaps.directions_layer(start, end, waypoints)


There is a limitation in the number of waypoints allowed by Google (currently 23). If it fails to return directions, a DirectionsServiceException is raised.

>>> directions_layer = gmaps.Directions(data=data*10)
Traceback (most recent call last):
...
DirectionsServiceException: No directions returned: MAX WAYPOINTS EXCEEDED

Parameters: data (list of tuples of length >= 2) – List of (latitude, longitude) pairs denoting a single point. The first pair denotes the starting point and the last pair denote the end of the route. Latitudes are expressed as a float between -90 (corresponding to 90 degrees south) and +90 (corresponding to 90 degrees north). Longitudes are expressed as a float between -180 (corresponding to 180 degrees west) and 180 (corresponding to 180 degrees east). travel_mode (str, optional) – Choose the mode of transport. One of 'BICYCLING', 'DRIVING', 'WALKING' or 'TRANSIT'. A travel mode of 'TRANSIT' indicates public transportation. Defaults to 'DRIVING'. avoid_ferries (bool, optional) – Avoids ferries where possible. avoid_highways (bool, optional) – Avoids highways where possible. avoid_tolls (bool, optional) – Avoids toll roads where possible. optimize_waypoints (bool, optional) – Attempt to re-order the supplied intermediate waypoints to minimize overall cost of the route.
class gmaps.Bicycling(**kwargs)

Bicycling layer.

Add this to a gmaps.Map or gmaps.Figure instance to add cycling routes.

You should not instantiate this directly. Instead, use the gmaps.bicycling_layer() factory function.

>>> fig = gmaps.figure()

class gmaps.Transit(**kwargs)

Transit layer.

Add this to a gmaps.Map or a gmaps.Figure instance to add transit (public transport) information. This only affects regions for which Google has transit information.

You should not instantiate this directly. Instead, use the gmaps.transit_layer() factory function.

# map centered on London
>>> fig = gmaps.figure(center=(51.5, -0.2), zoom_level=11)
>>> fig

class gmaps.Traffic(**kwargs)

Traffic layer

Add this to a gmaps.Map or a gmaps.Figure instance to add traffic information to the map, where supported.

You should not instantiate this directly. Instead, use the gmaps.traffic_layer() factory function.

# map centered on London
>>> fig = gmaps.figure(center=(51.5, -0.2), zoom_level=11)
>>> fig

Parameters: auto_refresh (bool, optional) – Whether the traffic layer refreshes with updated information automatically. This is true by default.

## Datasets¶

gmaps.datasets.list_datasets()

List of datasets available

gmaps.datasets.dataset_metadata(dataset_name)

This returns a dictionary containing a ‘description’, a list of the dataset headers and optionally information about the dataset source.

>>> dataset_metadata("earthquakes")
{'description': 'Taxi pickup location data in San Francisco',

gmaps.datasets.load_dataset(dataset_name)

Fetch a dataset, returning an array of tuples.

gmaps.datasets.load_dataset_as_df(dataset_name)

Fetch a dataset, returning a pandas dataframe.

## GeoJSON geometries¶

gmaps.geojson_geometries.list_geometries()

List of GeoJSON geometries available

gmaps.geojson_geometries.geometry_metadata(geometry_name)

This returns a dictionary containing a ‘description’.

>>> geometry_metadata("countries")
{'description': 'Map of world countries'}

gmaps.geojson_geometries.load_geometry(geometry_name)

Fetch a geometry.

Returns: A python dictionary containing the geometry.
>>> import gmaps
>>> import gmaps.geojson_geometries
>>> gmaps.configure(api_key="AIza...")

>>> fig = gmaps.figure()
>>> gini_layer = gmaps.geojson_layer(countries_geojson)
>>> fig


## Traitlets¶

class gmaps.geotraitlets.ColorAlpha(default_value=traitlets.Undefined, allow_none=False, **metadata)

Trait representing a color that can be passed to Google maps.

This is either a string like ‘blue’ or ‘#aabbcc’ or an RGB tuple like (100, 0, 250) or an RGBA tuple like (100, 0, 250, 0.5).

validate(obj, value)

Verifies that ‘value’ is a string or tuple and converts it to a value like ‘rgb(x,y,z)’

class gmaps.geotraitlets.ColorString(default_value=traitlets.Undefined, allow_none=False, read_only=None, help=None, config=None, **kwargs)

A string holding a color recognized by Google Maps.

Apparently Google Maps accepts ‘all CSS3 colors, including RGBA, [...] except for extended named colors and HSL(A) values’.

Using this <https://www.w3.org/TR/css3-color/#html4> page for reference.

default_value = traitlets.Undefined
class gmaps.geotraitlets.Latitude(default_value=traitlets.Undefined, allow_none=False, **kwargs)

Float representing a latitude

Latitude values must be between -90 and 90.

default_value = traitlets.Undefined
class gmaps.geotraitlets.Longitude(default_value=traitlets.Undefined, allow_none=False, **kwargs)

Float representing a longitude

Longitude values must be between -180 and 180.

default_value = traitlets.Undefined
class gmaps.geotraitlets.Point(default_value)

Tuple representing a (latitude, longitude) pair.

class gmaps.geotraitlets.ZoomLevel(default_value=traitlets.Undefined, allow_none=False, **kwargs)

Integer representing a zoom value allowed by Google Maps

default_value = traitlets.Undefined