add new map types

Author: LiamConnors

doc/python/filled-area-on-mapbox.md

@@ -5,10 +5,10 @@ jupyter:
     text_representation:
       extension: .md
       format_name: markdown
-      format_version: '1.1'
-      jupytext_version: 1.1.1
+      format_version: '1.3'
+      jupytext_version: 1.16.3
   kernelspec:
-    display_name: Python 3
+    display_name: Python 3 (ipykernel)
     language: python
     name: python3
   language_info:
@@ -20,68 +20,63 @@ jupyter:
     name: python
     nbconvert_exporter: python
     pygments_lexer: ipython3
-    version: 3.6.8
+    version: 3.10.0
   plotly:
-    description: How to make an area on Map in Python with Plotly.
+    description: How to make an area on tile-based maps in Python with Plotly.
     display_as: maps
     language: python
     layout: base
     name: Filled Area on Maps
     order: 3
     page_type: example_index
-    permalink: python/filled-area-on-mapbox/
+    permalink: python/filled-area-tile-maps/
+    redirect_from: python/filled-area-on-mapbox/
     thumbnail: thumbnail/area.jpg
 ---
 
-<!-- #region -->
-
-### 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.
+There are three different ways to show a filled area on a tile-based map:
 
-There are three different ways to show a filled area in a Mapbox map:
+- Using a [Scattermap](https://plotly.com/python/reference/scattermap/) trace and set `fill` attribute to 'toself'
+- Using a map layout (i.e. by minimally using an empty [Scattermap](https://plotly.com/python/reference/scattermap/) trace) and adding a GeoJSON layer
+- Using the [Choroplethmap](https://plotly.com/python/tile-county-choropleth/) trace type
 
-1. Use a [Scattermapbox](https://plotly.com/python/reference/scattermapbox/) trace and set `fill` attribute to 'toself'
-2. Use a Mapbox layout (i.e. by minimally using an empty [Scattermapbox](https://plotly.com/python/reference/scattermapbox/) trace) and add a GeoJSON layer
-3. Use the [Choroplethmapbox](https://plotly.com/python/mapbox-county-choropleth/) trace type
-   <!-- #endregion -->
+## Filled `Scattermap` Trace
 
-### Filled `Scattermapbox` Trace
-
-The following example uses `Scattermapbox` and sets `fill = 'toself'`
+The following example uses Scattermap and sets fill = 'toself'
 
 ```python
 import plotly.graph_objects as go
 
-fig = go.Figure(go.Scattermapbox(
+fig = go.Figure(go.Scattermap(
     fill = "toself",
     lon = [-74, -70, -70, -74], lat = [47, 47, 45, 45],
     marker = { 'size': 10, 'color': "orange" }))
 
 fig.update_layout(
-    mapbox = {
+    map = {
         'style': "open-street-map",
         'center': {'lon': -73, 'lat': 46 },
         'zoom': 5},
     showlegend = False)
 
 fig.show()
+
 ```
 
-### Multiple Filled Areas with a `Scattermapbox` trace
+### Multiple Filled Areas with a `Scattermap` trace
 
-The following example shows how to use `None` in your data to draw multiple filled areas. Such gaps in trace data are unconnected by default, but this can be controlled via the [connectgaps](https://plotly.com/python/reference/scattermapbox/#scattermapbox-connectgaps) attribute.
+The following example shows how to use `None` in your data to draw multiple filled areas. Such gaps in trace data are unconnected by default, but this can be controlled via the [connectgaps](https://plotly.com/python/reference/scattermap/#scattermap-connectgaps) attribute.
 
 ```python
 import plotly.graph_objects as go
 
-fig = go.Figure(go.Scattermapbox(
+fig = go.Figure(go.Scattermap(
     mode = "lines", fill = "toself",
     lon = [-10, -10, 8, 8, -10, None, 30, 30, 50, 50, 30, None, 100, 100, 80, 80, 100],
     lat = [30, 6, 6, 30, 30,    None, 20, 30, 30, 20, 20, None, 40, 50, 50, 40, 40]))
 
 fig.update_layout(
-    mapbox = {'style': "open-street-map", 'center': {'lon': 30, 'lat': 30}, 'zoom': 2},
+    map = {'style': "open-street-map", 'center': {'lon': 30, 'lat': 30}, 'zoom': 2},
     showlegend = False,
     margin = {'l':0, 'r':0, 'b':0, 't':0})
 
@@ -95,13 +90,13 @@ In this map we add a GeoJSON layer.
 ```python
 import plotly.graph_objects as go
 
-fig = go.Figure(go.Scattermapbox(
+fig = go.Figure(go.Scattermap(
     mode = "markers",
     lon = [-73.605], lat = [45.51],
     marker = {'size': 20, 'color': ["cyan"]}))
 
 fig.update_layout(
-    mapbox = {
+    map = {
         'style': "open-street-map",
         'center': { 'lon': -73.6, 'lat': 45.5},
         'zoom': 12, 'layers': [{
@@ -139,6 +134,34 @@ fig.update_layout(
 fig.show()
 ```
 
+<!-- #region -->
+### Mapbox Maps
+
+The earlier examples using `go.Scattermap` use Maplibre for rendering. These traces were introduced in Plotly.py 5.24. This trace types is now the recommended way to draw filled areas on tile-based maps. There is also a trace that uses Mapbox, called `go.Scattermapbox`.
+
+To use the `Scattermapbox` trace type, in some cases 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 one of the earlier examples rewritten to use `Scattermapbox`.
+
+```python
+import plotly.graph_objects as go
+
+fig = go.Figure(go.Scattermapbox(
+    fill = "toself",
+    lon = [-74, -70, -70, -74], lat = [47, 47, 45, 45],
+    marker = { 'size': 10, 'color': "orange" }))
+
+fig.update_layout(
+    mapbox = {
+        'style': "open-street-map",
+        'center': {'lon': -73, 'lat': 46 },
+        'zoom': 5},
+    showlegend = False)
+
+fig.show()
+```
+<!-- #endregion -->
+
 #### Reference
 
-See https://plotly.com/python/reference/scattermapbox/ for more information about mapbox and their attribute options.
+See  https://plotly.com/python/reference/scattermap/ for available attribute options, or for `go.Scattermapbox`, see https://plotly.com/python/reference/scattermapbox/.