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 agmaps.WeightedHeatmap
object that can be added to agmaps.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 agmaps.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 thelocations
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 aslocations
, or a single value. If given as a single value, this value will be broadcast to every marker. Thus, these two calls are equivalent:>>> symbol_layer = gmaps.symbol_layer( locations, fill_color=['red']*len(locations)) >>> symbol_layer = gmaps.symbol_layer( locations, fill_color='red')
The former is useful for passing different colours to different symbols.
>>> colors = ['red', 'green', 'blue', 'black', 'white'] >>> symbol_layer = gmaps.symbol_layer( locations, fill_color=colors, stro
To change the number of symbols after the layer has been constructed, mutate the
markers
attribute. You will need to pass a list ofgmaps.Symbol
instances explicitly.>>> symbol_layer.markers = [ gmaps.Symbol(location=(1.0, 2.0)), gmaps.Symbol(location=(3.0, 4.0)) ]
To change the style of symbols on an existing layer, mutate the symbol directly.
>>> symbol_layer.markers[0].scale = 5
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 thelocations
argument.Examples: >>> fig = gmaps.figure() >>> locations = [ (-34.0, -59.166672), (-32.23333, -64.433327), (40.166672, 44.133331), (51.216671, 5.0833302) ] >>> marker_layer = gmaps.marker_layer(locations) >>> fig.add_layer(marker_layer)
You can customize the markers by passing arguments to
marker_layer
:>>> marker_layer = gmaps.marker_layer( locations, hover_text=['Atucha', 'Embalse', 'Armenia', 'Br'] )
To change the number of markers on an existing layer, mutate the
markers
attribute. You will need to pass a list ofgmaps.Marker
orgmaps.Symbol
instances explicitly.>>> marker_layer.markers = [ gmaps.Marker(location=(1.0, 2.0)), gmaps.Marker(location=(3.0, 4.0)) ]
To change the style of markers on an existing layer, mutate the marker directly.
>>> marker_layer.markers[0].label = 'C' # markers[0] is a Marker
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
orgmaps.Polygon
. - marker_options (
gmaps.MarkerOptions
, dict or None, optional) – Options controlling how markers are drawn on the map. Either pass in an instance ofgmaps.MarkerOptions
, or a dictionary with keys hover_text, display_info_box, info_box_content, label (or a subset of these). Seegmaps.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 thegmaps.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 ofgmaps.LineOptions
, or a dictionary with keys stroke_weight, stroke_color, stroke_opacity (or a subset of these). Seegmaps.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 thegmaps.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 ofgmaps.PolygonOptions
, or a dictionary with keys stroke_weight, stroke_color, stroke_opacity, fill_color, fill_opacity (or a subset of these). Seegmaps.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 thegmaps.Polygon
constructor. - mode (str, optional) – Initial drawing mode. One of
DISABLED
,MARKER
,LINE
,POLYGON
orDELETE
. Defaults toMARKER
ifshow_controls
is True, otherwise defaults toDISABLED
. - show_controls (bool, optional) – Whether to show the drawing controls in the map toolbar. Defaults to True.
Returns: A
gmaps.Drawing
widget.- features (list of features, optional) – List of features to draw on the map. Features must be one of
-
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 thegmaps.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'
- initial_viewport – Define the initial zoom level and map centre. You should
construct this using one of the static methods on
-
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)
-
static
-
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
ifinfo_box_content
is not an empty string, orFalse
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 thegmaps.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
ifinfo_box_content
is not an empty string, orFalse
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)¶ Marker and symbol layer
This class represent a layer of markers and symbols. Add this to a
gmaps.Map
instance to draw a set of markers or symbols.In general, prefer instantiating this using the higher-level
gmaps.marker_layer()
andgmaps.symbol_layer()
factory functions.Parameters: markers (list of gmaps.Marker
andgmaps.Symbol
objects.) – Markers and symbols to draw on the map.Examples: >>> fig = gmaps.figure() >>> locations = [ (-34.0, -59.166672), (-32.23333, -64.433327), (40.166672, 44.133331), (51.216671, 5.0833302) ] >>> marker_layer = gmaps.marker_layer(locations) >>> fig.add_layer(marker_layer)
You can customize the markers by passing arguments to
marker_layer
:>>> marker_layer = gmaps.marker_layer( locations, hover_text=['Atucha', 'Embalse', 'Armenia', 'Br'] )
To change the number of markers on an existing layer, mutate the
markers
attribute. You will need to pass a list ofgmaps.Marker
orgmaps.Symbol
instances explicitly.>>> marker_layer.markers = [ gmaps.Marker(location=(1.0, 2.0)), gmaps.Marker(location=(3.0, 4.0)) ]
To change the style of markers or symbols on an existing layer mutate the marker directly.
>>> marker_layer.markers[0].label = 'C' # markers[0] is a Marker >>> marker_layer.markers[0].scale = 5 # markers[0] is a Symbol
-
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
orgmaps.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 agmaps.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 agmaps.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
orgmaps.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
orgmaps.Polygon
. - marker_options (
gmaps.MarkerOptions
, dict or None, optional) – Options controlling how markers are drawn on the map. Either pass in an instance ofgmaps.MarkerOptions
, or a dictionary with keys hover_text, display_info_box, info_box_content, label (or a subset of these). Seegmaps.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 thegmaps.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 ofgmaps.LineOptions
, or a dictionary with keys stroke_weight, stroke_color, stroke_opacity (or a subset of these). Seegmaps.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 thegmaps.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 ofgmaps.PolygonOptions
, or a dictionary with keys stroke_weight, stroke_color, stroke_opacity, fill_color, fill_opacity (or a subset of these). Seegmaps.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 thegmaps.Polygon
constructor. - mode (str, optional) – Initial drawing mode. One of
DISABLED
,MARKER
,LINE
,POLYGON
orDELETE
. Defaults toMARKER
iftoolbar_controls.show_controls
is True, otherwise defaults toDISABLED
. - 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
orgmaps.Polygon
.
- features (list of features, optional) – List of features to draw on the map. Features must be one of
-
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 ofgmaps.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 ofgmaps.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