API documentation

Figures and layers

gmaps.figure(display_toolbar=True, display_errors=True, zoom_level=None, tilt=45, center=None, layout=None, map_type='ROADMAP', mouse_handling='COOPERATIVE')

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.
  • tilt (int, optional) – Tilt can be either 0 or 45 indicating the tilt angle in degrees. 45-degree imagery is only available for satellite and hybrid map types, and is not available at every location at every zoom level. For locations where 45-degree imagery is not available, Google Maps will automatically fall back to 0 tilt.
  • 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.
  • map_type (str, optional) – String representing the type of map to show. One of ‘ROADMAP’ (the classic Google Maps style) ‘SATELLITE’ (just satellite tiles with no overlay), ‘HYBRID’ (satellite base tiles but with features such as roads and cities overlaid) and ‘TERRAIN’ (map showing terrain features). Defaults to ‘ROADMAP’.
  • mouse_handling (str, optional) – String representing how the map captures the page’s mouse event. One of ‘COOPERATIVE’ (scroll events scroll the page without zooming the map, double clicks or CTRL/CMD+scroll zoom the map), ‘GREEDY’ (the map captures all scroll events), ‘NONE’ (the map cannot be zoomed or panned by user gestures) or ‘AUTO’ (cooperative if the notebook is displayed in an iframe, greedy otherwise). Defaults to ‘COOPERATIVE’.
  • layout (dict, optional) – Control the layout of the figure, e.g. its width, height, border etc. For instance, passing layout={'width': '400px', 'height': '300px'} will build a figure of fixed width and height. For more in formation on available properties, see the ipywidgets documentation on widget layout.
Returns:

A gmaps.Figure widget.

Examples:
>>> import gmaps
>>> gmaps.configure(api_key="AI...")
>>> fig = gmaps.figure()
>>> locations = [(46.1, 5.2), (46.2, 5.3), (46.3, 5.4)]
>>> fig.add_layer(gmaps.heatmap_layer(locations))

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

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

To customise the layout:

>>> fig = gmaps.figure(layout={
        'width': '400px',
        'height': '600px',
        'padding': '3px',
        'border': '1px solid black'
})

To have a satellite map:

>>> fig = gmaps.figure(map_type='HYBRID')
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
Examples:
>>> 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
>>> heatmap.point_radius = 3
>>> heatmap.gradient = ['white', 'gray']
>>> fig.add_layer(heatmap)
Parameters:
  • locations (iterable of latitude, longitude pairs) – Iterable 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). This can be passed in as either a list of tuples, a two-dimensional numpy array or a pandas dataframe with two columns, in which case the first one is taken to be the latitude and the second one is taken to be the longitude.
  • weights (iterable of floats, optional) – Iterable of weights of the same length as locations. All the weights must be positive.
  • max_intensity (float, optional) – Strictly positive floating point number indicating the numeric value that corresponds to the hottest colour in the heatmap gradient. Any density of points greater than that value will just get mapped to the hottest colour. Setting this value can be useful when your data is sharply peaked. It is also useful if you find that your heatmap disappears as you zoom in.
  • point_radius (int, optional) – Number of pixels for each point passed in the data. This determines the “radius of influence” of each data point.
  • dissipating (bool, optional) – Whether the radius of influence of each point changes as you zoom in or out. If dissipating is True, the radius of influence of each point increases as you zoom out and decreases as you zoom in. If False, the radius of influence remains the same. Defaults to True.
  • opacity (float, optional) – The opacity of the heatmap layer. Defaults to 0.6.
  • gradient (list of colors, optional) – The color gradient for the heatmap. This must be specified as a list of colors. Google Maps then interpolates linearly between those colors. 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).
Returns:

A gmaps.Heatmap or a gmaps.WeightedHeatmap widget.

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.

Examples:
>>> 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')
>>> fig.add_layer(symbols)

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.

Examples:
>>> 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)
>>> fig.add_layer(markers)
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.

Examples:

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
>>> countries = json.loads(countries_string)
>>> import gmaps
>>> gmaps.configure(api_key="AI...")
>>> fig = gmaps.figure()
>>> geojson = gmaps.geojson_layer(countries)
>>> fig.add_layer(geojson)
>>> 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.drawing_layer(features=None, mode='MARKER', show_controls=True, marker_options=None, line_options=None, polygon_options=None)

Create an interactive drawing layer

Adding a drawing layer to a map allows adding custom shapes, both programatically and interactively (by drawing on the map).

Examples:

You can use the drawing layer to add lines, markers and polygons to a map:

>>> fig = gmaps.figure()
>>> drawing = gmaps.drawing_layer(features=[
     gmaps.Line((46.23, 5.86), (46.44, 5.24), stroke_weight=3.0),
     gmaps.Marker((46.88, 5.45), label='D'),
     gmaps.Polygon(
         [(46.72, 6.06), (46.48, 6.49), (46.79, 6.91)],
         fill_color='red'
     )
])
>>> fig.add_layer(drawing)
>>> fig

You can also use the drawing layer as a way to get user input. The user can draw features on the map. You can then get the list of features programatically.

>>> fig = gmaps.figure()
>>> drawing = gmaps.drawing_layer()
>>> fig.add_layer(drawing)
>>> fig
>>> # Now draw on the map
>>> drawing.features
[Marker(location=(46.83, 5.56)),
Marker(location=(46.46, 5.91)),
Line(end=(46.32, 5.98), start=(46.42, 5.12))]

You can bind callbacks that are executed when a new feature is added. For instance, you can use geopy to get the address corresponding to markers that you add on the map:

API_KEY = "Aiz..."

import gmaps
import geopy

gmaps.configure(api_key=API_KEY)
fig = gmaps.figure()
drawing = gmaps.drawing_layer()

geocoder = geopy.geocoders.GoogleV3(api_key=API_KEY)

def print_address(feature):
    try:
        print(geocoder.reverse(feature.location, exactly_one=True))
    except AttributeError as e:
        # Not a marker
        pass

drawing.on_new_feature(print_feature)
fig.add_layer(drawing)
fig  # display the figure
Parameters:
  • features (list of features, optional) – List of features to draw on the map. Features must be one of gmaps.Marker, gmaps.Line or gmaps.Polygon.
  • marker_options (gmaps.MarkerOptions, dict or None, optional) – Options controlling how markers are drawn on the map. Either pass in an instance of gmaps.MarkerOptions, or a dictionary with keys hover_text, display_info_box, info_box_content, label (or a subset of these). See gmaps.MarkerOptions for documentation on possible values. Note that this only affects the initial options of markers added to the map by a user. To customise markers added programatically, pass in the options to the gmaps.Marker constructor.
  • line_options (gmaps.LineOptions, dict or None, optional) – Options controlling how new lines are drawn on the map. Either pass in an instance of gmaps.LineOptions, or a dictionary with keys stroke_weight, stroke_color, stroke_opacity (or a subset of these). See gmaps.LineOptions for documentation on possible values. Note that this only affects the initial options of lines added to the map by a user. To customise lines added programatically, pass in the options to the gmaps.Line constructor.
  • polygon_options (gmaps.PolygonOptions, dict or None, optional) – Options controlling how new polygons are drawn on the map. Either pass in an instance of gmaps.PolygonOptions, or a dictionary with keys stroke_weight, stroke_color, stroke_opacity, fill_color, fill_opacity (or a subset of these). See gmaps.PolygonOptions for documentation on possible values. Note that this only affects the initial options of polygons added to the map by a user. To customise polygons added programatically, pass in the options to the gmaps.Polygon constructor.
  • mode (str, optional) – Initial drawing mode. One of DISABLED, MARKER, LINE, POLYGON or DELETE. Defaults to MARKER if show_controls is True, otherwise defaults to DISABLED.
  • show_controls (bool, optional) – Whether to show the drawing controls in the map toolbar. Defaults to True.
Returns:

A gmaps.Drawing widget.

gmaps.directions_layer(start, end, waypoints=None, avoid_ferries=False, travel_mode='DRIVING', avoid_highways=False, avoid_tolls=False, optimize_waypoints=False, show_markers=True, show_route=True, stroke_color='#0088FF', stroke_weight=6.0, stroke_opacity=0.6)

Create a directions layer.

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

Examples:
>>> fig = gmaps.figure()
>>> start = (46.2, 6.1)
>>> end = (47.4, 8.5)
>>> directions = gmaps.directions_layer(start, end)
>>> fig.add_layer(directions)
>>> 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')

You can choose to hide the markers, the route or both:

>>> directions = gmaps.directions_layer(
        start, end, show_markers=False, show_route=False)

Control how the route is displayed by changing the stroke_color, stroke_weight and stroke_opacity attributes.

>>> directions = gmaps.directions_layer(
        start, end, stroke_color='red',
        stroke_opacity=1.0, stroke_weight=2.0)

You can update parameters on an existing layer. This will automatically update the map:

>>> directions.travel_mode = 'DRIVING'
>>> directions.start = (46.4, 6.1)
>>> directions.stroke_color = 'green'
>>> directions.show_markers = False
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.
  • show_markers (bool, optional) – If set to False, the markers showing the start, destination and waypoints are explicitly hidden. Defaults to True.
  • show_route (bool, optional) – If set to False, the line indicating the route is explicitly hidden. Defaults to True.
  • stroke_color (str or tuple, optional) – The stroke color of the line indicating the route. 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). Defaults to a blue color: (0, 88, 255)
  • stroke_weight (float, optional) – The width of the line indicating the route. This is a positive float. Defaults to 6.
  • stroke_opacity (float, optional) – The opacity of the stroke color. The opacity should be a float between 0.0 (transparent) and 1.0 (opaque). 0.6 by default.
Returns:

A gmaps.Directions widget.

gmaps.bicycling_layer()

Bicycling layer.

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

Returns:A gmaps.Bicycling widget.
Examples:
>>> fig = gmaps.figure()
>>> fig.add_layer(gmaps.bicycling_layer())
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.
Examples:
# map centered on London
>>> fig = gmaps.figure(center=(51.5, -0.2), zoom_level=11)
>>> fig.add_layer(gmaps.transit_layer())
>>> 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.
Returns:A gmaps.Traffic widget.
Examples:
# map centered on London
>>> fig = gmaps.figure(center=(51.5, -0.2), zoom_level=11)
>>> fig.add_layer(gmaps.traffic_layer())
>>> fig

Utility functions

gmaps.configure(api_key=None)

Configure access to the GoogleMaps API.

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(*args, **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.
Examples:
>>> f = figure()
>>> fig.add_layer(gmaps.heatmap_layer(locations))

See also

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.drawing_layer()
Create a layer of custom features, and allow users to draw on the map
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.
  • map_type (str, optional) – String representing the type of map to show. One of ‘ROADMAP’ (the classic Google Maps style) ‘SATELLITE’ (just satellite tiles with no overlay), ‘HYBRID’ (satellite base tiles but with features such as roads and cities overlaid) and ‘TERRAIN’ (map showing terrain features). Defaults to ‘ROADMAP’.
  • mouse_handling (str, optional) – String representing how the map captures the page’s mouse event. One of ‘COOPERATIVE’ (scroll events scroll the page without zooming the map, double clicks or CTRL/CMD+scroll zoom the map), ‘GREEDY’ (the map captures all scroll events), ‘NONE’ (the map cannot be zoomed or panned by user gestures) or ‘AUTO’ (cooperative if the notebook is displayed in an iframe, greedy otherwise). Defaults to ‘COOPERATIVE’.
Examples:
>>> m = gmaps.Map()
>>> m.add_layer(gmaps.heatmap_layer(locations))

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.Map(initial_viewport=viewport)

To have a satellite map:

>>> m = gmaps.Map(map_type='HYBRID')

You can also change this dynamically:

>>> m.map_type = 'TERRAIN'
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.

Examples:
>>> 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.
Examples:
>>> 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.

Parameters:
  • locations (iterable of latitude, longitude pairs) – Iterable 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). This can be passed in as either a list of tuples, a two-dimensional numpy array or a pandas dataframe with two columns, in which case the first one is taken to be the latitude and the second one is taken to be the longitude.
  • max_intensity (float, optional) – Strictly positive floating point number indicating the numeric value that corresponds to the hottest colour in the heatmap gradient. Any density of points greater than that value will just get mapped to the hottest colour. Setting this value can be useful when your data is sharply peaked. It is also useful if you find that your heatmap disappears as you zoom in.
  • point_radius (int, optional) – Number of pixels for each point passed in the data. This determines the “radius of influence” of each data point.
  • dissipating (bool, optional) – Whether the radius of influence of each point changes as you zoom in or out. If dissipating is True, the radius of influence of each point increases as you zoom out and decreases as you zoom in. If False, the radius of influence remains the same. Defaults to True.
  • opacity (float, optional) – The opacity of the heatmap layer. Defaults to 0.6.
  • gradient (list of colors, optional) – The color gradient for the heatmap. This must be specified as a list of colors. Google Maps then interpolates linearly between those colors. 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).
  • data (list of tuples) – DEPRECATED. Use locations instead. 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).
Examples:
>>> 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
>>> heatmap.point_radius = 3
>>> heatmap.gradient = ['white', 'gray']
>>> fig.add_layer(heatmap_layer)
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.

Parameters:
  • locations (iterable of latitude, longitude pairs) – Iterable 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). This can be passed in as either a list of tuples, a two-dimensional numpy array or a pandas dataframe with two columns, in which case the first one is taken to be the latitude and the second one is taken to be the longitude.
  • weights (list of floats) – List of non-negative floats corresponding to the importance of each latitude-longitude pair. Must have the same length as locations.
  • max_intensity (float, optional) – Strictly positive floating point number indicating the numeric value that corresponds to the hottest colour in the heatmap gradient. Any density of points greater than that value will just get mapped to the hottest colour. Setting this value can be useful when your data is sharply peaked. It is also useful if you find that your heatmap disappears as you zoom in.
  • point_radius (int, optional) – Number of pixels for each point passed in the data. This determines the “radius of influence” of each data point.
  • dissipating (bool, optional) – Whether the radius of influence of each point changes as you zoom in or out. If dissipating is True, the radius of influence of each point increases as you zoom out and decreases as you zoom in. If False, the radius of influence remains the same. Defaults to True.
  • opacity (float, optional) – The opacity of the heatmap layer. Defaults to 0.6.
  • gradient (list of colors, optional) – The color gradient for the heatmap. This must be specified as a list of colors. Google Maps then interpolates linearly between those colors. 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).
  • data (list of tuples) – DEPRECATED. Use locations and weights instead. List of (latitude, longitude, weight) triples for 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). Weights must be non-negative.
Examples:
>>> 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
>>> fig.add_layer(heatmap_layer)
class gmaps.Symbol(location, **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.MarkerOptions(**kwargs)

Style options for a marker

Parameters:
  • label (string, optional) – Text to be displayed inside the marker. Google maps only displays the first letter of this string.
  • hover_text (string, optional) – Text to be displayed when a user’s mouse is hovering over the marker. If this is set to an empty string, nothing will appear when the user’s mouse hovers over a marker.
  • display_info_box (bool, optional) – Whether to display an info box when the user clicks on a marker. Defaults to True if info_box_content is not an empty string, or False otherwise.
  • info_box_content (string, optional) – Content to be displayed in a box above a marker, when the user clicks on it.
class gmaps.Marker(location, **kwargs)

Class representing a marker.

Markers should be added to the map via the gmaps.marker_layer() function or the gmaps.drawing_layer() function.

Parameters:
  • location (tuple of floats) – (latitude, longitude) pair denoting the location of the marker. 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).
  • label (string, optional) – Text to be displayed inside the marker. Google maps only displays the first letter of this string.
  • hover_text (string, optional) – Text to be displayed when a user’s mouse is hovering over the marker. If this is set to an empty string, nothing will appear when the user’s mouse hovers over a marker.
  • display_info_box (bool, optional) – Whether to display an info box when the user clicks on a marker. Defaults to True if info_box_content is not an empty string, or False otherwise.
  • info_box_content (string, optional) – Content to be displayed in a box above a marker, when the user clicks on it.
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(start=None, end=None, waypoints=None, **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.

Examples:
>>> fig = gmaps.figure()
>>> start = (46.2, 6.1)
>>> end = (47.4, 8.5)
>>> directions = gmaps.directions_layer(start, end)
>>> fig.add_layer(directions)
>>> 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')

You can choose to hide the markers, the route or both:

>>> directions = gmaps.directions_layer(
        start, end, show_markers=False, show_route=False)

Control how the route is displayed by changing the stroke_color, stroke_weight and stroke_opacity attributes.

>>> directions = gmaps.directions_layer(
        start, end, stroke_color='red',
        stroke_opacity=1.0, stroke_weight=2.0)

You can update parameters on an existing layer. This will automatically update the map:

>>> directions.travel_mode = 'DRIVING'
>>> directions.start = (46.4, 6.1)
>>> directions.stroke_color = 'green'
>>> directions.show_markers = False
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.
  • show_markers (bool, optional) – If set to False, the markers showing the start, destination and waypoints are explicitly hidden. Defaults to True.
  • show_route (bool, optional) – If set to False, the line indicating the route is explicitly hidden. Defaults to True.
  • stroke_color (str or tuple, optional) – The stroke color of the line indicating the route. 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). Defaults to a blue color: (0, 88, 255)
  • stroke_weight (float, optional) – The width of the line indicating the route. This is a positive float. Defaults to 6.
  • stroke_opacity (float, optional) – The opacity of the stroke color. The opacity should be a float between 0.0 (transparent) and 1.0 (opaque). 0.6 by default.
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.

Examples:
>>> fig = gmaps.figure()
>>> fig.add_layer(gmaps.bicycling_layer())
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.

Examples:
# map centered on London
>>> fig = gmaps.figure(center=(51.5, -0.2), zoom_level=11)
>>> fig.add_layer(gmaps.transit_layer())
>>> 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.

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

Widget for a drawing layer

Add this to a gmaps.Map or gmaps.Figure instance to let you draw on the map.

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

Examples:

You can use the drawing layer to add lines, markers and polygons to a map:

>>> fig = gmaps.figure()
>>> drawing = gmaps.drawing_layer(features=[
     gmaps.Line((46.23, 5.86), (46.44, 5.24), stroke_weight=3.0),
     gmaps.Marker((46.88, 5.45), label='D'),
     gmaps.Polygon(
         [(46.72, 6.06), (46.48, 6.49), (46.79, 6.91)],
         fill_color='red'
     )
])
>>> fig.add_layer(drawing)
>>> fig

You can also use the drawing layer as a way to get user input. The user can draw features on the map. You can then get the list of features programatically.

>>> fig = gmaps.figure()
>>> drawing = gmaps.drawing_layer()
>>> fig.add_layer(drawing)
>>> fig
>>> # Now draw on the map
>>> drawing.features
[Marker(location=(46.83, 5.56)),
Marker(location=(46.46, 5.91)),
Line(end=(46.32, 5.98), start=(46.42, 5.12))]

You can bind callbacks that are executed when a new feature is added. For instance, you can use geopy to get the address corresponding to markers that you add on the map:

API_KEY = "Aiz..."

import gmaps
import geopy

gmaps.configure(api_key=API_KEY)
fig = gmaps.figure()
drawing = gmaps.drawing_layer()

geocoder = geopy.geocoders.GoogleV3(api_key=API_KEY)

def print_address(feature):
    try:
        print(geocoder.reverse(feature.location, exactly_one=True))
    except AttributeError as e:
        # Not a marker
        pass

drawing.on_new_feature(print_feature)
fig.add_layer(drawing)
fig  # display the figure
Parameters:
  • features (list of features, optional) – List of features to draw on the map. Features must be one of gmaps.Marker, gmaps.Line or gmaps.Polygon.
  • marker_options (gmaps.MarkerOptions, dict or None, optional) – Options controlling how markers are drawn on the map. Either pass in an instance of gmaps.MarkerOptions, or a dictionary with keys hover_text, display_info_box, info_box_content, label (or a subset of these). See gmaps.MarkerOptions for documentation on possible values. Note that this only affects the initial options of markers added to the map by a user. To customise markers added programatically, pass in the options to the gmaps.Marker constructor.
  • line_options (gmaps.LineOptions, dict or None, optional) – Options controlling how new lines are drawn on the map. Either pass in an instance of gmaps.LineOptions, or a dictionary with keys stroke_weight, stroke_color, stroke_opacity (or a subset of these). See gmaps.LineOptions for documentation on possible values. Note that this only affects the initial options of lines added to the map by a user. To customise lines added programatically, pass in the options to the gmaps.Line constructor.
  • polygon_options (gmaps.PolygonOptions, dict or None, optional) – Options controlling how new polygons are drawn on the map. Either pass in an instance of gmaps.PolygonOptions, or a dictionary with keys stroke_weight, stroke_color, stroke_opacity, fill_color, fill_opacity (or a subset of these). See gmaps.PolygonOptions for documentation on possible values. Note that this only affects the initial options of polygons added to the map by a user. To customise polygons added programatically, pass in the options to the gmaps.Polygon constructor.
  • mode (str, optional) – Initial drawing mode. One of DISABLED, MARKER, LINE, POLYGON or DELETE. Defaults to MARKER if toolbar_controls.show_controls is True, otherwise defaults to DISABLED.
  • toolbar_controls (gmaps.DrawingControls, optional) – Widget representing the drawing toolbar.
on_new_feature(callback)

Register a callback called when new features are added

Parameters:callback (callable) – Callable to be called when a new feature is added. The callback should take a single argument, the feature that has been added. This can be an instance of gmaps.Line, gmaps.Marker or gmaps.Polygon.
class gmaps.DrawingControls(**kwargs)

Widget for the toolbar snippet representing the drawing controls

Parameters:show_controls (bool, optional) – Whether the drawing controls should be shown. Defaults to True.
class gmaps.Line(start, end, stroke_color='#696969', stroke_weight=2.0, stroke_opacity=0.6)

Widget representing a single line on a map

Add this line to a map via the gmaps.drawing_layer() function, or by passing it directly to the .features array of an existing instance of gmaps.Drawing.

Examples:
>>> fig = gmaps.figure()
>>> drawing = gmaps.drawing_layer(features=[
     gmaps.Line((46.44, 5.24), (46.23, 5.86), stroke_color='green'),
     gmaps.Line((48.44, 1.32), (47.13, 3.91), stroke_weight=5.0)
])
>>> fig.add_layer(drawing)

You can also add a line to an existing gmaps.Drawing instance:

>>> fig = gmaps.figure()
>>> drawing = gmaps.drawing_layer()
>>> fig.add_layer(drawing)
>>> fig # display the figure

You can now add lines directly on the map:

>>> drawing.features = [
     gmaps.Line((46.44, 5.24), (46.23, 5.86), stroke_color='green'),
     gmaps.Line((48.44, 1.32), (47.13, 3.91), stroke_weight=5.0)
]
Parameters:
  • start (tuple of floats) – (latitude, longitude) pair denoting the start of the line. 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).
  • end – (latitude, longitude) pair denoting the end of the line. 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).
  • stroke_color (str or tuple, optional) – The stroke color of the line. 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). Defaults to a grey color: (69, 69, 69)
  • stroke_weight (float, optional) – How wide the line is. This is a positive float. Defaults to 2.
  • stroke_opacity (float, optional) – The opacity of the stroke color. The opacity should be a float between 0.0 (transparent) and 1.0 (opaque). 0.6 by default.
class gmaps.LineOptions(*args, **kwargs)

Style options for a line

Pass an instance of this class to gmaps.drawing_layer() to control the style of new user-drawn lines on the map.

Examples:
>>> fig = gmaps.figure()
>>> drawing = gmaps.drawing_layer(
        marker_options=gmaps.MarkerOptions(hover_text='some text'),
        line_options=gmaps.LineOptions(stroke_color='red')
    )
>>> fig.add_layer(drawing)
>>> fig # display the figure
Parameters:
  • stroke_color (str or tuple, optional) – The stroke color of the line. 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). Defaults to a grey color: (69, 69, 69)
  • stroke_weight (float, optional) – How wide the line is. This is a positive float. Defaults to 2.
  • stroke_opacity (float, optional) – The opacity of the stroke color. The opacity should be a float between 0.0 (transparent) and 1.0 (opaque). 0.6 by default.
class gmaps.Polygon(path, stroke_color='#696969', stroke_weight=2.0, stroke_opacity=0.6, fill_color='#696969', fill_opacity=0.2)

Widget representing a closed polygon on a map

Add this polygon to a map via the gmaps.drawing_layer() function, or by passing it directly to the .features array of an existing instance of gmaps.Drawing.

Examples:
>>> fig = gmaps.figure()
>>> drawing = gmaps.drawing_layer(features=[
     gmaps.Polygon(
        [(46.72, 6.06), (46.48, 6.49), (46.79, 6.91)],
        stroke_color='red', fill_color=(255, 0, 132)
    )
])
>>> fig.add_layer(drawing)

You can also add a polygon to an existing gmaps.Drawing instance:

>>> fig = gmaps.figure()
>>> drawing = gmaps.drawing_layer()
>>> fig.add_layer(drawing)
>>> fig # display the figure

You can now add polygons directly on the map:

>>> drawing.features = [
     gmaps.Polygon(
         [(46.72, 6.06), (46.48, 6.49), (46.79, 6.91)]
         stroke_color='red', fill_color=(255, 0, 132)
     )
]
Parameters:
  • path (list of tuples of floats) – List of (latitude, longitude) pairs denoting each point on the polygon. 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).
  • stroke_color (str or tuple, optional) – The stroke color of the line. 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). Defaults to a grey color: (69, 69, 69)
  • stroke_weight (float, optional) – How wide the line is. This is a positive float. Defaults to 2.
  • stroke_opacity (float, optional) – The opacity of the stroke color. The opacity should be a float between 0.0 (transparent) and 1.0 (opaque). 0.6 by default.
  • fill_color (str or tuple, optional) – The internal color of the polygon. 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). Defaults to a grey color: (69, 69, 69)
  • fill_opacity (float, optional) – The opacity of the fill color. The opacity should be a float between 0.0 (transparent) and 1.0 (opaque). 0.2 by default.
class gmaps.PolygonOptions(*args, **kwargs)

Style options for a polygon.

Pass an instance of this class to gmaps.drawing_layer() to control the style of new user-drawn polygons on the map.

Examples:
>>> fig = gmaps.figure()
>>> drawing = gmaps.drawing_layer(
        polygon_options=gmaps.PolygonOptions(
            stroke_color='red', fill_color=(255, 0, 132))
    )
>>> fig.add_layer(drawing)
>>> fig # display the figure
Parameters:
  • stroke_color (str or tuple, optional) – The stroke color of the line. 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). Defaults to a grey color: (69, 69, 69)
  • stroke_weight (float, optional) – How wide the line is. This is a positive float. Defaults to 2.
  • stroke_opacity (float, optional) – The opacity of the stroke color. The opacity should be a float between 0.0 (transparent) and 1.0 (opaque). 0.6 by default.
  • fill_color (str or tuple, optional) – The internal color of the polygon. 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). Defaults to a grey color: (69, 69, 69)
  • fill_opacity (float, optional) – The opacity of the fill color. The opacity should be a float between 0.0 (transparent) and 1.0 (opaque). 0.2 by default.

Datasets

gmaps.datasets.list_datasets()

List of datasets available

gmaps.datasets.dataset_metadata(dataset_name)

Information about the dataset

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

Examples:
>>> dataset_metadata("earthquakes")
{'description': 'Taxi pickup location data in San Francisco',
 'headers': ['latitude', 'longitude']}
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)

Information about the geometry.

This returns a dictionary containing a ‘description’.

Examples:
>>> 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.
Examples:
>>> import gmaps
>>> import gmaps.geojson_geometries
>>> gmaps.configure(api_key="AIza...")
>>> countries_geojson = gmaps.geojson_geometries.load_geometry('countries')
>>> fig = gmaps.figure()
>>> gini_layer = gmaps.geojson_layer(countries_geojson)
>>> fig.add_layer(gini_layer)
>>> 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
exception gmaps.geotraitlets.InvalidPointException
exception gmaps.geotraitlets.InvalidWeightException
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.LocationArray(trait=None, default_value=None, minlen=0, maxlen=9223372036854775807, **kwargs)
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.MapType(default_value, **kwargs)

String representing a map type

class gmaps.geotraitlets.MouseHandling(default_value, **kwargs)

String representing valid values for mouse handling

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

Tuple representing a (latitude, longitude) pair.

class gmaps.geotraitlets.RgbTuple(**metadata)
class gmaps.geotraitlets.RgbaTuple(**metadata)
class gmaps.geotraitlets.Tilt(default_value=traitlets.Undefined, allow_none=False, **kwargs)

Integer representing a tilt degree allowed by Google Maps

class gmaps.geotraitlets.WeightArray(trait=None, default_value=None, minlen=0, maxlen=9223372036854775807, **kwargs)
default_value = traitlets.Undefined
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