Skip to content

Commit b01917d

Browse files
nicolaskruchtennicolaskruchten
committed
new mapbox docs
1 parent dac58ba commit b01917d

File tree

4 files changed

+288
-42
lines changed

4 files changed

+288
-42
lines changed

‎python/mapbox-county-choropleth.md

Lines changed: 46 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@ jupyter:
2222
pygments_lexer: ipython3
2323
version: 3.6.7
2424
plotly:
25-
description: How to make a Mapbox Choropleth Map of the Florida Counties in Python
25+
description: How to make a Mapbox Choropleth Map of US Counties in Python
2626
with Plotly.
2727
display_as: maps
2828
has_thumbnail: true
@@ -37,55 +37,60 @@ jupyter:
3737
title: Python Mapbox Choropleth Maps | plotly
3838
---
3939

40+
4041
#### Mapbox Access Token
4142

43+
To plot on Mapbox maps with Plotly you *may* need a Mapbox account and a public [Mapbox Access Token](https://www.mapbox.com/studio). See our [Mapbox Map Layers](/python/mapbox-layers/) documentation for more information.
44+
4245

43-
To plot on Mapbox maps with Plotly you'll need a Mapbox account and a [Mapbox Access Token](https://www.mapbox.com/studio) which you can add to your [Plotly settings](https://plot.ly/settings/mapbox). If you're using a Chart Studio Enterprise server, please see additional instructions here: https://help.plot.ly/mapbox-atlas/.
46+
#### Mapbox Light base map: free token needed
4447

4548
```python
49+
token = open(".mapbox_token").read() # you will need your own token
50+
51+
52+
from urllib.request import urlopen
53+
import json
54+
with urlopen('https://raw.githubusercontent.com/plotly/datasets/master/geojson-counties-fips.json') as response:
55+
counties = json.load(response)
56+
57+
import pandas as pd
58+
unemp = pd.read_csv("https://raw.githubusercontent.com/plotly/datasets/master/fips-unemp-16.csv",
59+
dtype={"fips": str})
60+
4661
import plotly.graph_objects as go
4762

48-
mapbox_access_token = open(".mapbox_token").read()
49-
50-
fig = go.Figure(go.Scattermapbox(
51-
lat=['45.5017'],
52-
lon=['-73.5673'],
53-
mode='markers',
54-
))
55-
56-
fig.update_layout(
57-
height=600,
58-
autosize=True,
59-
hovermode='closest',
60-
mapbox=dict(
61-
layers=[
62-
dict(
63-
sourcetype = 'geojson',
64-
source = 'https://raw.githubusercontent.com/plotly/datasets/master/florida-red-data.json',
65-
type = 'fill',
66-
color = 'rgba(163,22,19,0.8)'
67-
),
68-
dict(
69-
sourcetype = 'geojson',
70-
source = 'https://raw.githubusercontent.com/plotly/datasets/master/florida-blue-data.json',
71-
type = 'fill',
72-
color = 'rgba(40,0,113,0.8)'
73-
)
74-
],
75-
accesstoken=mapbox_access_token,
76-
bearing=0,
77-
center=dict(
78-
lat=27.8,
79-
lon=-83
80-
),
81-
pitch=0,
82-
zoom=5.2,
83-
style='light'
84-
),
85-
)
63+
fig = go.Figure(go.Choroplethmapbox(geojson=counties, locations=unemp.fips, z=unemp.unemp,
64+
colorscale="Viridis", zmin=0, zmax=12))
65+
fig.update_layout(mapbox_style="light", mapbox_accesstoken=token,
66+
mapbox_zoom=3, mapbox_center = {"lat": 37.0902, "lon": -95.7129})
67+
fig.update_layout(margin={"r":0,"t":0,"l":0,"b":0})
68+
fig.show()
69+
```
70+
71+
72+
#### Carto base map: no token needed
73+
74+
```python
75+
from urllib.request import urlopen
76+
import json
77+
with urlopen('https://raw.githubusercontent.com/plotly/datasets/master/geojson-counties-fips.json') as response:
78+
counties = json.load(response)
79+
80+
import pandas as pd
81+
unemp = pd.read_csv("https://raw.githubusercontent.com/plotly/datasets/master/fips-unemp-16.csv",
82+
dtype={"fips": str})
83+
84+
import plotly.graph_objects as go
8685

86+
fig = go.Figure(go.Choroplethmapbox(geojson=counties, locations=unemp.fips, z=unemp.unemp,
87+
colorscale="Viridis", zmin=0, zmax=12,
88+
marker_opacity=0.5, marker_line_width=0))
89+
fig.update_layout(mapbox_style="carto-positron",
90+
mapbox_zoom=3, mapbox_center = {"lat": 37.0902, "lon": -95.7129})
91+
fig.update_layout(margin={"r":0,"t":0,"l":0,"b":0})
8792
fig.show()
8893
```
8994

9095
#### Reference
91-
See https://plot.ly/python/reference/#scattermapbox for more information about mapbox and their attribute options.
96+
See https://plot.ly/python/reference/#choroplethmapbox for more information about mapbox and their attribute options.

‎python/mapbox-density-heatmaps.md

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
---
2+
jupyter:
3+
jupytext:
4+
notebook_metadata_filter: all
5+
text_representation:
6+
extension: .md
7+
format_name: markdown
8+
format_version: '1.1'
9+
jupytext_version: 1.1.1
10+
kernelspec:
11+
display_name: Python 3
12+
language: python
13+
name: python3
14+
language_info:
15+
codemirror_mode:
16+
name: ipython
17+
version: 3
18+
file_extension: .py
19+
mimetype: text/x-python
20+
name: python
21+
nbconvert_exporter: python
22+
pygments_lexer: ipython3
23+
version: 3.6.7
24+
plotly:
25+
description: How to make a Mapbox Density Heatmap in Python
26+
with Plotly.
27+
display_as: maps
28+
has_thumbnail: true
29+
ipynb: ~notebook_demo/56
30+
language: python
31+
layout: user-guide
32+
name: Mapbox Density Heatmap
33+
order: 1.5
34+
page_type: u-guide
35+
permalink: python/mapbox-density-heatmaps/
36+
thumbnail: thumbnail/county-level-choropleth.jpg
37+
title: Python Density Heatmap | plotly
38+
---
39+
40+
41+
#### Mapbox Access Token
42+
43+
To plot on Mapbox maps with Plotly you *may* need a Mapbox account and a public [Mapbox Access Token](https://www.mapbox.com/studio). See our [Mapbox Map Layers](/python/mapbox-layers/) documentation for more information.
44+
45+
46+
47+
48+
#### Stamen Terrain base map: no token needed
49+
50+
```python
51+
import pandas as pd
52+
quakes = pd.read_csv('https://raw.githubusercontent.com/plotly/datasets/master/earthquakes-23k.csv')
53+
54+
import plotly.graph_objects as go
55+
fig = go.Figure(go.Densitymapbox(lat=quakes.Latitude, lon=quakes.Longitude, z=quakes.Magnitude, radius=10))
56+
fig.update_layout(mapbox_style="stamen-terrain", mapbox_center_lon=180)
57+
fig.update_layout(margin={"r":0,"t":0,"l":0,"b":0})
58+
fig.show()
59+
```
60+
61+
#### Reference
62+
See https://plot.ly/python/reference/#densitymapbox for more information about mapbox and their attribute options.

‎python/mapbox-layers.md

Lines changed: 179 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,179 @@
1+
---
2+
jupyter:
3+
jupytext:
4+
notebook_metadata_filter: all
5+
text_representation:
6+
extension: .md
7+
format_name: markdown
8+
format_version: '1.1'
9+
jupytext_version: 1.1.1
10+
kernelspec:
11+
display_name: Python 3
12+
language: python
13+
name: python3
14+
language_info:
15+
codemirror_mode:
16+
name: ipython
17+
version: 3
18+
file_extension: .py
19+
mimetype: text/x-python
20+
name: python
21+
nbconvert_exporter: python
22+
pygments_lexer: ipython3
23+
version: 3.6.8
24+
plotly:
25+
description: How to make Mapbox maps in Python with various base layers, with
26+
or without needing a Mapbox Access token.
27+
display_as: maps
28+
has_thumbnail: true
29+
ipynb: ~notebook_demo/261
30+
language: python
31+
layout: user-guide
32+
name: Mapbox Map Layers
33+
order: 7
34+
page_type: example_index
35+
permalink: python/mapbox-layers/
36+
thumbnail: thumbnail/scatter-mapbox.jpg
37+
title: Mapbox Map Layers in Python | Plotly
38+
---
39+
40+
<!-- #region -->
41+
#### How Layers Work in Mapbox Maps
42+
43+
If your figure contains one or more traces of type `go.Scattermapbox`, `go.Choroplethmapbox` or `go.Densitymapbox`, the `layout.mapbox` object in your figure contains configuration information for the map itself. The map is composed of various layers, of three different types:
44+
45+
1. `layout.mapbox.style` defines is the lowest layers, also known as your "base map"
46+
2. The various traces in `data` are by default rendered above the base map (although this can be controlled via the `below` attribute).
47+
3. `layout.mapbox.layers` is an array that defines more layers that are by default rendered above the traces in `data` (although this can also be controlled via the `below` attribute).
48+
49+
#### Mapbox Access Tokens and When You Need Them
50+
51+
The word "mapbox" in the trace names and `layout.mapbox` refers to the Mapbox.js open-source library, which is integrated into Plotly.py. If your basemap in `layout.mapbox.style` uses data from the Mapbox *service*, then you will need to register for a free account at https://mapbox.com/ and obtain a Mapbox Access token. This token should be provided in `layout.mapbox.access_token` (or, if using Plotly Express, via the `px.set_mapbox_access_token()` configuration function).
52+
53+
> If your `layout.mapbox.style` does not use data from the Mapbox service, you do *not* need to register for a Mapbox account.
54+
55+
#### Base Maps in `layout.mapbox.style`
56+
57+
The accepted values for `layout.mapbox.style` are one of:
58+
59+
* `"white-bg"` yields an empty white canvas which results in no external HTTP requests
60+
* `"open-street-map"`, `"carto-positron"`, `"carto-darkmatter"`, `"stamen-terrain"`, `"stamen-toner"` or `"stamen-watercolor"` yeild maps composed of *raster* tiles from various public tile servers which do not require signups or access tokens
61+
* `"basic"`, `"streets"`, `"outdoors"`, `"light"`, `"dark"`, `"satellite"`, or `"satellite-streets"` yeild maps composed of *vector* tiles from the Mapbox service, and *do* require a Mapbox Access Token or an on-premise Mapbox installation.
62+
* A Mapbox service style URL, which requires a Mapbox Access Token or an on-premise Mapbox installation.
63+
* A Mapbox Style object as defined at https://docs.mapbox.com/mapbox-gl-js/style-spec/
64+
65+
66+
67+
#### OpenStreetMap tiles: no token needed
68+
Here is a simple map rendered with OpenStreetMaps tiles, without needing a Mapbox Access Token:
69+
<!-- #endregion -->
70+
71+
```python
72+
import pandas as pd
73+
us_cities = pd.read_csv("https://raw.githubusercontent.com/plotly/datasets/master/us-cities-top-1k.csv")
74+
75+
import plotly.express as px
76+
77+
fig = px.scatter_mapbox(us_cities, lat="lat", lon="lon", hover_name="City", hover_data=["State", "Population"],
78+
color_discrete_sequence=["fuchsia"], zoom=3, height=300)
79+
fig.update_layout(mapbox_style="open-street-map")
80+
fig.update_layout(margin={"r":0,"t":0,"l":0,"b":0})
81+
fig.show()
82+
```
83+
84+
<!-- #region -->
85+
#### Dark tiles from Mapbox service: free token needed
86+
87+
88+
Here is the same map rendered with the `"dark"` style from the Mapbox service, which requires an Access Token:
89+
<!-- #endregion -->
90+
91+
```python
92+
token = open(".mapbox_token").read() # you will need your own token
93+
94+
import pandas as pd
95+
us_cities = pd.read_csv("https://raw.githubusercontent.com/plotly/datasets/master/us-cities-top-1k.csv")
96+
97+
import plotly.express as px
98+
99+
fig = px.scatter_mapbox(us_cities, lat="lat", lon="lon", hover_name="City", hover_data=["State", "Population"],
100+
color_discrete_sequence=["fuchsia"], zoom=3, height=300)
101+
fig.update_layout(mapbox_style="dark", mapbox_accesstoken=token)
102+
fig.update_layout(margin={"r":0,"t":0,"l":0,"b":0})
103+
fig.show()
104+
```
105+
106+
<!-- #region -->
107+
#### Using `layout.mapbox.layers` to Specify a Base Map
108+
109+
If you have access to your own private tile servers, or wish to use a tile server not included in the list above, the recommended approach is to set `layout.mapbox.style` to `"white-bg"` and to use `layout.mapbox.layers` with `below` to specify a custom base map.
110+
111+
112+
> If you omit the `below` attribute when using this approach, your data will likely be hidden by fully-opaque raster tiles!
113+
114+
#### Base Tiles from the USGS: no token needed
115+
116+
Here is an example of a map which uses a public USGS imagery map, specified in `layout.mapbox.layers`, and which is rendered *below* the `data` layer.
117+
<!-- #endregion -->
118+
119+
```python
120+
import pandas as pd
121+
us_cities = pd.read_csv("https://raw.githubusercontent.com/plotly/datasets/master/us-cities-top-1k.csv")
122+
123+
import plotly.express as px
124+
125+
fig = px.scatter_mapbox(us_cities, lat="lat", lon="lon", hover_name="City", hover_data=["State", "Population"],
126+
color_discrete_sequence=["fuchsia"], zoom=3)
127+
fig.update_layout(
128+
mapbox_style="white-bg",
129+
mapbox_layers=[
130+
{
131+
"below": 'traces',
132+
"sourcetype": "raster",
133+
"source": [
134+
"https://basemap.nationalmap.gov/arcgis/rest/services/USGSImageryOnly/MapServer/tile/{z}/{y}/{x}"
135+
]
136+
}
137+
])
138+
fig.update_layout(margin={"r":0,"t":0,"l":0,"b":0})
139+
fig.show()
140+
```
141+
142+
<!-- #region -->
143+
#### Base Tiles from the USGS, radar overlay from Environment Canada: no token needed
144+
145+
146+
Here is the same example, with in addition, a WMS layer from Environment Canada which displays near-real-time radar imagery in partly-transparent raster tiles, rendered above the `go.Scattermapbox` trace, as is the default:
147+
<!-- #endregion -->
148+
149+
```python
150+
import pandas as pd
151+
us_cities = pd.read_csv("https://raw.githubusercontent.com/plotly/datasets/master/us-cities-top-1k.csv")
152+
153+
import plotly.express as px
154+
155+
fig = px.scatter_mapbox(us_cities, lat="lat", lon="lon", hover_name="City", hover_data=["State", "Population"],
156+
color_discrete_sequence=["fuchsia"], zoom=3)
157+
fig.update_layout(
158+
mapbox_style="white-bg",
159+
mapbox_layers=[
160+
{
161+
"below": 'traces',
162+
"sourcetype": "raster",
163+
"source": [
164+
"https://basemap.nationalmap.gov/arcgis/rest/services/USGSImageryOnly/MapServer/tile/{z}/{y}/{x}"
165+
]
166+
},
167+
{
168+
"sourcetype": "raster",
169+
"source": ["https://geo.weather.gc.ca/geomet/?"
170+
"SERVICE=WMS&VERSION=1.3.0&REQUEST=GetMap&BBOX={bbox-epsg-3857}&CRS=EPSG:3857"
171+
"&WIDTH=1000&HEIGHT=1000&LAYERS=RADAR_1KM_RDBR&TILED=true&FORMAT=image/png"],
172+
}
173+
])
174+
fig.update_layout(margin={"r":0,"t":0,"l":0,"b":0})
175+
fig.show()
176+
```
177+
178+
#### Reference
179+
See https://plot.ly/python/reference/#layout-mapbox for more information and options!

‎python/scattermapbox.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,7 @@ jupyter:
3939

4040
#### Mapbox Access Token
4141

42-
To plot on Mapbox maps with Plotly you'll need a Mapbox account and a public [Mapbox Access Token](https://www.mapbox.com/studio) which you can add to your [Plotly settings](https://plot.ly/settings/mapbox). If you're using a Chart Studio Enterprise server, please see additional instructions here: https://help.plot.ly/mapbox-atlas/.
42+
To plot on Mapbox maps with Plotly you *may* need a Mapbox account and a public [Mapbox Access Token](https://www.mapbox.com/studio). See our [Mapbox Map Layers](/python/mapbox-layers/) documentation for more information.
4343

4444
### Basic example with Plotly Express
4545

0 commit comments

Comments
 (0)