Update scattermapbox.md

Author: LiamConnors

doc/python/scattermapbox.md

@@ -6,7 +6,7 @@ jupyter:
       extension: .md
       format_name: markdown
       format_version: '1.3'
-      jupytext_version: 1.16.2
+      jupytext_version: 1.16.3
   kernelspec:
     display_name: Python 3 (ipykernel)
     language: python
@@ -22,48 +22,43 @@ jupyter:
     pygments_lexer: ipython3
     version: 3.10.0
   plotly:
-    description: How to make scatter plots on Mapbox maps in Python.
+    description: How to make scatter plots on tile maps in Python.
     display_as: maps
     language: python
     layout: base
     name: Scatter Plots on Mapbox
     order: 9
     page_type: u-guide
-    permalink: python/scattermapbox/
+    permalink: python/tile-scatter-maps/
     thumbnail: thumbnail/scatter-mapbox.jpg
+    redirect_from: python/scattermapbox/
 ---
 
-#### Mapbox Access Token and Base Map Configuration
-
-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.
-
 ### Basic example with Plotly Express
 
-Here we show the [Plotly Express](/python/plotly-express/) function `px.scatter_mapbox` for a scatter plot on a tile map.
+Here we show the [Plotly Express](/python/plotly-express/) function `px.scatter_map` for a scatter plot on a tile map.
 
 [Plotly Express](/python/plotly-express/) is the easy-to-use, high-level interface to Plotly, which [operates on a variety of types of data](/python/px-arguments/) and produces [easy-to-style figures](/python/styling-plotly-express/).
 
 ```python
 import plotly.express as px
-px.set_mapbox_access_token(open(".mapbox_token").read())
 df = px.data.carshare()
-fig = px.scatter_mapbox(df, lat="centroid_lat", lon="centroid_lon",     color="peak_hour", size="car_hours",
+fig = px.scatter_map(df, lat="centroid_lat", lon="centroid_lon",     color="peak_hour", size="car_hours",
                   color_continuous_scale=px.colors.cyclical.IceFire, size_max=15, zoom=10)
 fig.show()
 ```
 
 ### Basic Example with GeoPandas
 
-`px.scatter_mapbox` can work well with [GeoPandas](https://geopandas.org/) dataframes whose `geometry` is of type `Point`.
+`px.scatter_map` can work well with [GeoPandas](https://geopandas.org/) dataframes whose `geometry` is of type `Point`.
 
 ```python
 import plotly.express as px
 import geopandas as gpd
 
 geo_df = gpd.read_file(gpd.datasets.get_path('naturalearth_cities'))
 
-px.set_mapbox_access_token(open(".mapbox_token").read())
-fig = px.scatter_mapbox(geo_df,
+fig = px.scatter_map(geo_df,
                         lat=geo_df.geometry.y,
                         lon=geo_df.geometry.x,
                         hover_name="name",
@@ -76,24 +71,21 @@ fig.show()
 ```python
 import plotly.graph_objects as go
 
-mapbox_access_token = open(".mapbox_token").read()
-
-fig = go.Figure(go.Scattermapbox(
+fig = go.Figure(go.Scattermap(
         lat=['45.5017'],
         lon=['-73.5673'],
         mode='markers',
-        marker=go.scattermapbox.Marker(
+        marker=go.scattermap.Marker(
             size=14
         ),
         text=['Montreal'],
     ))
 
 fig.update_layout(
     hovermode='closest',
-    mapbox=dict(
-        accesstoken=mapbox_access_token,
+    map=dict(
         bearing=0,
-        center=go.layout.mapbox.Center(
+        center=go.layout.map.Center(
             lat=45,
             lon=-73
         ),
@@ -110,9 +102,7 @@ fig.show()
 ```python
 import plotly.graph_objects as go
 
-mapbox_access_token = open(".mapbox_token").read()
-
-fig = go.Figure(go.Scattermapbox(
+fig = go.Figure(go.Scattermap(
         lat=['38.91427','38.91538','38.91458',
              '38.92239','38.93222','38.90842',
              '38.91931','38.93260','38.91368',
@@ -124,7 +114,7 @@ fig = go.Figure(go.Scattermapbox(
              '-76.99656','-77.042438','-77.02821',
              '-77.01239'],
         mode='markers',
-        marker=go.scattermapbox.Marker(
+        marker=go.scattermap.Marker(
             size=9
         ),
         text=["The coffee bar","Bistro Bohem","Black Cat",
@@ -137,8 +127,7 @@ fig = go.Figure(go.Scattermapbox(
 fig.update_layout(
     autosize=True,
     hovermode='closest',
-    mapbox=dict(
-        accesstoken=mapbox_access_token,
+    map=dict(
         bearing=0,
         center=dict(
             lat=38.92,
@@ -158,20 +147,18 @@ fig.show()
 import plotly.graph_objects as go
 import pandas as pd
 
-mapbox_access_token = open(".mapbox_token").read()
-
 df = pd.read_csv('https://raw.githubusercontent.com/plotly/datasets/master/Nuclear%20Waste%20Sites%20on%20American%20Campuses.csv')
 site_lat = df.lat
 site_lon = df.lon
 locations_name = df.text
 
 fig = go.Figure()
 
-fig.add_trace(go.Scattermapbox(
+fig.add_trace(go.Scattermap(
         lat=site_lat,
         lon=site_lon,
         mode='markers',
-        marker=go.scattermapbox.Marker(
+        marker=go.scattermap.Marker(
             size=17,
             color='rgb(255, 0, 0)',
             opacity=0.7
@@ -180,11 +167,11 @@ fig.add_trace(go.Scattermapbox(
         hoverinfo='text'
     ))
 
-fig.add_trace(go.Scattermapbox(
+fig.add_trace(go.Scattermap(
         lat=site_lat,
         lon=site_lon,
         mode='markers',
-        marker=go.scattermapbox.Marker(
+        marker=go.scattermap.Marker(
             size=8,
             color='rgb(242, 177, 172)',
             opacity=0.7
@@ -197,8 +184,7 @@ fig.update_layout(
     autosize=True,
     hovermode='closest',
     showlegend=False,
-    mapbox=dict(
-        accesstoken=mapbox_access_token,
+    map=dict(
         bearing=0,
         center=dict(
             lat=38,
@@ -215,7 +201,7 @@ fig.show()
 
 ### Set Marker Symbols
 
-You can define a symbol on your map by setting [symbol](https://plotly.com/python/reference/scattermapbox/#scattermapbox-marker-symbol) attribute. This attribute only works on Mapbox-provided `style`s:
+You can define a symbol on your map by setting [symbol](https://plotly.com/python/reference/scattermap/#scattermap-marker-symbol) attribute.
 
 - basic
 - streets
@@ -228,17 +214,14 @@ You can define a symbol on your map by setting [symbol](https://plotly.com/pytho
 ```python
 import plotly.graph_objects as go
 
-token = open(".mapbox_token").read() # you need your own token
-
-fig = go.Figure(go.Scattermapbox(
+fig = go.Figure(go.Scattermap(
     mode = "markers+text+lines",
     lon = [-75, -80, -50], lat = [45, 20, -20],
     marker = {'size': 20, 'symbol': ["bus", "harbor", "airport"]},
     text = ["Bus", "Harbor", "airport"],textposition = "bottom right"))
 
 fig.update_layout(
-    mapbox = {
-        'accesstoken': token,
+    map = {
         'style': "outdoors", 'zoom': 0.7},
     showlegend = False)
 
@@ -255,26 +238,23 @@ Display clusters of data points by setting `cluster`. Here, we enable clusters w
 import plotly.express as px
 import pandas as pd
 
-px.set_mapbox_access_token(open(".mapbox_token").read())
 df = pd.read_csv(
     "https://raw.githubusercontent.com/plotly/datasets/master/2011_february_us_airport_traffic.csv"
 )
-fig = px.scatter_mapbox(df, lat="lat", lon="long", size="cnt", zoom=3)
+fig = px.scatter_map(df, lat="lat", lon="long", size="cnt", zoom=3)
 fig.update_traces(cluster=dict(enabled=True))
 fig.show()
 
 ```
 
 #### Font Customization
 
-You can customize the font on `go.Scattermapbox` traces with `textfont`. For example, you can set the font `family`.
+You can customize the font on `go.Scattermap` traces with `textfont`. For example, you can set the font `family`.
 
 ```python
 import plotly.graph_objects as go
 
-token = open(".mapbox_token").read() # you need your own token
-
-fig = go.Figure(go.Scattermapbox(
+fig = go.Figure(go.Scattermap(
     mode = "markers+text+lines",
     lon = [-75, -80, -50], lat = [45, 20, -20],
     marker = {'size': 20, 'symbol': ["bus", "harbor", "airport"]},
@@ -283,15 +263,14 @@ fig = go.Figure(go.Scattermapbox(
     ))
 
 fig.update_layout(
-    mapbox = {
-        'accesstoken': token,
+    map = {
         'style': "outdoors", 'zoom': 0.7},
     showlegend = False,)
 
 fig.show()
 ```
 
-`go.Scattermapbox` supports the following values for `textfont.family`: 
+`go.Scattermap` supports the following values for `textfont.family`:
 
 'Metropolis Black Italic', 'Metropolis Black', 'Metropolis Bold Italic', 'Metropolis Bold', 'Metropolis Extra Bold Italic', 'Metropolis Extra Bold', 'Metropolis Extra Light Italic', 'Metropolis Extra Light', 'Metropolis Light Italic', 'Metropolis Light', 'Metropolis Medium Italic', 'Metropolis Medium', 'Metropolis Regular Italic', 'Metropolis Regular', 'Metropolis Semi Bold Italic', 'Metropolis Semi Bold', 'Metropolis Thin Italic', 'Metropolis Thin', 'Open Sans Bold Italic', 'Open Sans Bold', 'Open Sans Extrabold Italic', 'Open Sans Extrabold', 'Open Sans Italic', 'Open Sans Light Italic', 'Open Sans Light', 'Open Sans Regular', 'Open Sans Semibold Italic', 'Open Sans Semibold', 'Klokantech Noto Sans Bold', 'Klokantech Noto Sans CJK Bold', 'Klokantech Noto Sans CJK Regular', 'Klokantech Noto Sans Italic', and 'Klokantech Noto Sans Regular'.
 
@@ -300,14 +279,12 @@ fig.show()
 
 *New in 5.23*
 
-You can specify a numeric font weight on `go.Scattermapbox` with `textfont.weight`.
+You can specify a numeric font weight on `go.Scattermap` with `textfont.weight`.
 
 ```python
 import plotly.graph_objects as go
 
-token = open(".mapbox_token").read() # you need your own token
-
-fig = go.Figure(go.Scattermapbox(
+fig = go.Figure(go.Scattermap(
     mode = "markers+text+lines",
     lon = [-75, -80, -50], lat = [45, 20, -20],
     marker = dict(size=20, symbol=["bus", "harbor", "airport"]),
@@ -316,14 +293,71 @@ fig = go.Figure(go.Scattermapbox(
     ))
 
 fig.update_layout(
-    mapbox = dict(
-        accesstoken=token,
+    map = dict(
         style="outdoors", zoom=0.7),
     showlegend = False,)
 
 fig.show()
 ```
 
+## Mapbox Maps
+
+The earlier examples using `px.scatter_map` and `go.Scattermap` use Maplibre for rendering. These traces were introduced in Plotly.py 5.24. These trace types are now the recommended way to create scatter plots on tile-based maps. There are also traces that use Mapbox: `px.scatter_mapbox` and `go.Scattermapbox`
+
+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.
+
+Here's the first example rewritten to use `px.scatter_mapbox`.
+
+```python
+import plotly.express as px
+px.set_mapbox_access_token(open(".mapbox_token").read())
+df = px.data.carshare()
+fig = px.scatter_mapbox(df, lat="centroid_lat", lon="centroid_lon",     color="peak_hour", size="car_hours",
+                  color_continuous_scale=px.colors.cyclical.IceFire, size_max=15, zoom=10)
+fig.show()
+
+```
+
+And here's an example using Graph Objects:
+
+```python
+import plotly.graph_objects as go
+
+mapbox_access_token = open(".mapbox_token").read()
+
+fig = go.Figure(go.Scattermapbox(
+        lat=['45.5017'],
+        lon=['-73.5673'],
+        mode='markers',
+        marker=go.scattermapbox.Marker(
+            size=14
+        ),
+        text=['Montreal'],
+    ))
+
+fig.update_layout(
+    hovermode='closest',
+    mapbox=dict(
+        accesstoken=mapbox_access_token,
+        bearing=0,
+        center=go.layout.mapbox.Center(
+            lat=45,
+            lon=-73
+        ),
+        pitch=0,
+        zoom=5
+    )
+)
+
+fig.show()
+```
+
 #### Reference
 
-See [function reference for `px.(scatter_mapbox)`](https://plotly.com/python-api-reference/generated/plotly.express.scatter_mapbox) or https://plotly.com/python/reference/scattermapbox/ for more information and options!
+See [function reference for `px.(scatter_map)`](https://plotly.com/python-api-reference/generated/plotly.express.scatter_mapbox) or https://plotly.com/python/reference/scattermap/ for more information about the attributes available.
+
+For Mapbox-based tile maps, see [function reference for `px.(scatter_mapbox)`](https://plotly.com/python-api-reference/generated/plotly.express.scatter_mapbox) or https://plotly.com/python/reference/scattermapbox/.
+
+```python
+
+```