Mapbox Maps vs Geo Maps

Summary: This introduction shows the differences between Geo and Mapbox based geographical charts.

Plotly and therefore Plotly.NET supports two different kinds of maps:

Mapbox maps are tile-based maps. If your figure is created with a Chart.*Mapbox function or otherwise contains one or more traces of type scattermapbox, choroplethmapbox or densitymapbox, the layout.mapbox object in your figure contains configuration information for the map itself.
Geo maps are outline-based maps. If your figure is created with a Chart.ScatterGeo, Chart.PointGeo, Chart.LineGeo or Chart.Choropleth function or otherwise contains one or more traces of type scattergeo or choropleth, the layout.geo object in your figure contains configuration information for the map itself.

This page documents Mapbox tile-based maps, and the Geo map documentation describes how to configure outline-based maps

How Layers Work in Mapbox Tile Maps

Mapbox tile maps are composed of various layers, of three different types:

the style property of the Mapbox object defines is the lowest layers, also known as your "base map"
The various traces in data are by default rendered above the base map (although this can be controlled via the below attribute).
the layers property of the Mapbox object 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).

a Mapbox object where these properties can be set can be initialized via Mapbox.init. To use it in a chart, use the Chart.withMapbox function:

open Plotly.NET
open Plotly.NET.LayoutObjects

// a simple Mapbox with a OpenStreetMap base layer.
let mb = Mapbox.init (Style = StyleParam.MapboxStyle.OpenStreetMap)

let baseLayerOnly =
    Chart.PointMapbox(lonlat = []) // deliberately empty chart to show the base map only
    |> Chart.withMapbox mb // add the mapBox

Mapbox Access Tokens and When You Need Them

The word "mapbox" in the trace names and layout.mapbox refers to the Mapbox GL JS open-source library, which is integrated into Plotly.NET.

If your basemap 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 via the AccessToken property:

let mbWithToken =
    Mapbox.init (Style = StyleParam.MapboxStyle.OpenStreetMap, AccessToken = "your_token_here")

If your base map does not use data from the Mapbox service, you do not need to register for a Mapbox account.

Base Maps

WhiteBG yields an empty white canvas which results in no external HTTP requests
The plotly presets yield maps composed of raster tiles from various public tile servers which do not require signups or access tokens
The Mapbox presets yield maps composed of vector tiles from the Mapbox service, and do require a Mapbox Access Token or an on-premise Mapbox installation.
Use StyleParam.MapboxStyle.Custom for:
- Mapbox service style URL, which requires a Mapbox Access Token or an on-premise Mapbox installation.
- A Mapbox Style object as defined at https://docs.mapbox.com/mapbox-gl-js/style-spec/

The accepted values for the style property of the Mapbox object are represented in StyleParam.MapboxStyle:

type MapboxStyle =
    // plotly presets, no token needed
    | WhiteBG
    | OpenStreetMap
    | CartoPositron
    | CartoDarkmatter
    | StamenTerrain
    | StamenToner
    | StamenWatercolor

    // Mapbox presets, you might need a free token
    | MapboxBasic
    | MapboxStreets
    | MapboxOutdoors
    | MapboxLight
    | MapboxDark
    | MapboxSatellite
    | MapboxSatelliteStreets

    //Custom - provide custom maps
    | Custom of string

namespace Plotly

namespace Plotly.NET

module Defaults from Plotly.NET
<summary> Contains mutable global default values. Changing these values will apply the default values to all consecutive Chart generations. </summary>

val mutable DefaultDisplayOptions: Plotly.NET.DisplayOptions

Multiple items
type DisplayOptions = inherit DynamicObj new: unit -> DisplayOptions static member addAdditionalHeadTags: additionalHeadTags: XmlNode list -> (DisplayOptions -> DisplayOptions) static member addChartDescription: description: XmlNode list -> (DisplayOptions -> DisplayOptions) static member combine: first: DisplayOptions -> second: DisplayOptions -> DisplayOptions static member getAdditionalHeadTags: displayOpts: DisplayOptions -> XmlNode list static member getChartDescription: displayOpts: DisplayOptions -> XmlNode list static member getDocumentCharset: displayOpts: DisplayOptions -> string static member getDocumentDescription: displayOpts: DisplayOptions -> string static member getDocumentFavicon: displayOpts: DisplayOptions -> XmlNode ...

--------------------
new: unit -> Plotly.NET.DisplayOptions

static member Plotly.NET.DisplayOptions.init: ?DocumentTitle: string * ?DocumentCharset: string * ?DocumentDescription: string * ?DocumentFavicon: Giraffe.ViewEngine.HtmlElements.XmlNode * ?AdditionalHeadTags: Giraffe.ViewEngine.HtmlElements.XmlNode list * ?ChartDescription: Giraffe.ViewEngine.HtmlElements.XmlNode list * ?PlotlyJSReference: Plotly.NET.PlotlyJSReference -> Plotly.NET.DisplayOptions

type PlotlyJSReference = | CDN of string | Full | Require of string | NoReference
<summary> Sets how plotly is referenced in the head of html docs. </summary>

union case Plotly.NET.PlotlyJSReference.NoReference: Plotly.NET.PlotlyJSReference

namespace Plotly.NET.LayoutObjects

val mb: Mapbox

Multiple items
type Mapbox = inherit DynamicObj new: unit -> Mapbox static member init: ?Domain: Domain * ?AccessToken: string * ?Style: MapboxStyle * ?Bounds: MapboxBounds * ?Center: (float * float) * ?Zoom: float * ?Bearing: float * ?Pitch: float * ?Layers: MapboxLayer seq -> Mapbox static member style: ?Domain: Domain * ?AccessToken: string * ?Style: MapboxStyle * ?Bounds: MapboxBounds * ?Center: (float * float) * ?Zoom: float * ?Bearing: float * ?Pitch: float * ?Layers: MapboxLayer seq -> (Mapbox -> Mapbox)
<summary>Determines the style of the map shown in mapbox traces</summary>

--------------------
new: unit -> Mapbox

static member Mapbox.init: ?Domain: Domain * ?AccessToken: string * ?Style: StyleParam.MapboxStyle * ?Bounds: MapboxBounds * ?Center: (float * float) * ?Zoom: float * ?Bearing: float * ?Pitch: float * ?Layers: MapboxLayer seq -> Mapbox

module StyleParam from Plotly.NET

type MapboxStyle = | OpenStreetMap | WhiteBG | CartoPositron | CartoDarkmatter | StamenTerrain | StamenToner | StamenWatercolor | MapboxBasic | MapboxStreets | MapboxOutdoors ... member Convert: unit -> objnull override ToString: unit -> string static member convert: (MapboxStyle -> objnull) static member toString: (MapboxStyle -> string)
<summary> Defines the map layers that are rendered by default below the trace layers defined in `data`, which are themselves by default rendered below the layers defined in `layout.mapbox.layers`. These layers can be defined either explicitly as a Mapbox Style object which can contain multiple layer definitions that load data from any public or private Tile Map Service (TMS or XYZ) or Web Map Service (WMS) or implicitly by using one of the built-in style objects which use WMSes which do not require any access tokens, or by using a default Mapbox style or custom Mapbox style URL, both of which require a Mapbox access token Note that Mapbox access token can be set in the `accesstoken` attribute or in the `mapboxAccessToken` config option. Mapbox Style objects are of the form described in the Mapbox GL JS documentation available at https://docs.mapbox.com/mapbox-gl-js/style-spec The built-in plotly.js styles objects are: open-street-map, white-bg, carto-positron, carto-darkmatter, stamen-terrain, stamen-toner, stamen-watercolor The built-in Mapbox styles are: basic, streets, outdoors, light, dark, satellite, satellite-streets Mapbox style URLs are of the form: mapbox://mapbox.mapbox-<name>-<version> </summary>

union case StyleParam.MapboxStyle.OpenStreetMap: StyleParam.MapboxStyle

val baseLayerOnly: GenericChart

type Chart = static member Bubble: x: #IConvertible seq * y: #IConvertible seq * sizes: int seq * ?Name: string * ?ShowLegend: bool * ?Opacity: float * ?MultiOpacity: float seq * ?Text: 'c * ?MultiText: 'c seq * ?TextPosition: TextPosition * ?MultiTextPosition: TextPosition seq * ?MarkerColor: Color * ?MarkerColorScale: Colorscale * ?MarkerOutline: Line * ?MarkerSymbol: MarkerSymbol * ?MultiMarkerSymbol: MarkerSymbol seq * ?Marker: Marker * ?LineColor: Color * ?LineColorScale: Colorscale * ?LineWidth: float * ?LineDash: DrawingStyle * ?Line: Line * ?AlignmentGroup: string * ?OffsetGroup: string * ?StackGroup: string * ?Orientation: Orientation * ?GroupNorm: GroupNorm * ?UseWebGL: bool * ?UseDefaults: bool -> GenericChart (requires 'c :> IConvertible) + 2 overloads static member Line: x: #IConvertible seq * y: #IConvertible seq * ?ShowMarkers: bool * ?Name: string * ?ShowLegend: bool * ?Opacity: float * ?MultiOpacity: float seq * ?Text: 'c * ?MultiText: 'c seq * ?TextPosition: TextPosition * ?MultiTextPosition: TextPosition seq * ?MarkerColor: Color * ?MarkerColorScale: Colorscale * ?MarkerOutline: Line * ?MarkerSymbol: MarkerSymbol * ?MultiMarkerSymbol: MarkerSymbol seq * ?Marker: Marker * ?LineColor: Color * ?LineColorScale: Colorscale * ?LineWidth: float * ?LineDash: DrawingStyle * ?Line: Line * ?AlignmentGroup: string * ?OffsetGroup: string * ?StackGroup: string * ?Orientation: Orientation * ?GroupNorm: GroupNorm * ?Fill: Fill * ?FillColor: Color * ?FillPattern: Pattern * ?UseWebGL: bool * ?UseDefaults: bool -> GenericChart (requires 'c :> IConvertible) + 2 overloads static member Point: x: #IConvertible seq * y: #IConvertible seq * ?Name: string * ?ShowLegend: bool * ?Opacity: float * ?MultiOpacity: float seq * ?Text: 'c * ?MultiText: 'c seq * ?TextPosition: TextPosition * ?MultiTextPosition: TextPosition seq * ?MarkerColor: Color * ?MarkerColorScale: Colorscale * ?MarkerOutline: Line * ?MarkerSymbol: MarkerSymbol * ?MultiMarkerSymbol: MarkerSymbol seq * ?Marker: Marker * ?AlignmentGroup: string * ?OffsetGroup: string * ?StackGroup: string * ?Orientation: Orientation * ?GroupNorm: GroupNorm * ?UseWebGL: bool * ?UseDefaults: bool -> GenericChart (requires 'c :> IConvertible) + 2 overloads static member Range: x: #IConvertible seq * y: #IConvertible seq * upper: #IConvertible seq * lower: #IConvertible seq * mode: Mode * ?Name: string * ?GroupName: string * ?ShowMarkers: bool * ?ShowLegend: bool * ?Text: 'e * ?MultiText: 'e seq * ?TextPosition: TextPosition * ?MultiTextPosition: TextPosition seq * ?MarkerColor: Color * ?MarkerColorScale: Colorscale * ?MarkerOutline: Line * ?MarkerSymbol: MarkerSymbol * ?MultiMarkerSymbol: MarkerSymbol seq * ?Marker: Marker * ?UpperMarker: Marker * ?LowerMarker: Marker * ?LineColor: Color * ?LineColorScale: Colorscale * ?LineWidth: float * ?LineDash: DrawingStyle * ?Line: Line * ?UpperLine: Line * ?LowerLine: Line * ?RangeColor: Color * ?RangePattern: Pattern * ?UpperText: 'f * ?MultiUpperText: 'f seq * ?LowerText: 'g * ?MultiLowerText: 'g seq * ?TextFont: Font * ?LowerName: string * ?UpperName: string * ?UseDefaults: bool -> GenericChart (requires 'e :> IConvertible and 'f :> IConvertible and 'g :> IConvertible) + 2 overloads static member Scatter: ?X: 'a seq * ?XEncoded: EncodedTypedArray * ?MultiX: 'a seq seq * ?Y: 'b seq * ?YEncoded: EncodedTypedArray * ?MultiY: 'b seq seq * ?Mode: Mode * ?Name: string * ?ShowLegend: bool * ?Opacity: float * ?MultiOpacity: float seq * ?Text: 'c * ?MultiText: 'c seq * ?TextPosition: TextPosition * ?MultiTextPosition: TextPosition seq * ?MarkerColor: Color * ?MarkerColorScale: Colorscale * ?MarkerOutline: Line * ?MarkerSymbol: MarkerSymbol * ?MultiMarkerSymbol: MarkerSymbol seq * ?Marker: Marker * ?LineColor: Color * ?LineColorScale: Colorscale * ?LineWidth: float * ?LineDash: DrawingStyle * ?Line: Line * ?AlignmentGroup: string * ?OffsetGroup: string * ?StackGroup: string * ?Orientation: Orientation * ?GroupNorm: GroupNorm * ?Fill: Fill * ?FillColor: Color * ?FillPattern: Pattern * ?UseWebGL: bool * ?UseDefaults: bool -> GenericChart (requires 'a :> IConvertible and 'b :> IConvertible and 'c :> IConvertible) + 3 overloads static member Spline: x: #IConvertible seq * y: #IConvertible seq * ?ShowMarkers: bool * ?Smoothing: float * ?Name: string * ?ShowLegend: bool * ?Opacity: float * ?MultiOpacity: float seq * ?Text: 'c * ?MultiText: 'c seq * ?TextPosition: TextPosition * ?MultiTextPosition: TextPosition seq * ?MarkerColor: Color * ?MarkerColorScale: Colorscale * ?MarkerOutline: Line * ?MarkerSymbol: MarkerSymbol * ?MultiMarkerSymbol: MarkerSymbol seq * ?Marker: Marker * ?LineColor: Color * ?LineColorScale: Colorscale * ?LineWidth: float * ?LineDash: DrawingStyle * ?Line: Line * ?AlignmentGroup: string * ?OffsetGroup: string * ?StackGroup: string * ?Orientation: Orientation * ?GroupNorm: GroupNorm * ?Fill: Fill * ?FillColor: Color * ?FillPattern: Pattern * ?UseWebGL: bool * ?UseDefaults: bool -> GenericChart (requires 'c :> IConvertible) + 2 overloads

static member Chart.PointMapbox: lonlat: (#System.IConvertible * #System.IConvertible) seq * ?Name: string * ?MapboxStyle: StyleParam.MapboxStyle * ?ShowLegend: bool * ?Opacity: float * ?MultiOpacity: float seq * ?Text: 'c * ?MultiText: 'c seq * ?TextPosition: StyleParam.TextPosition * ?MultiTextPosition: StyleParam.TextPosition seq * ?MarkerColor: Color * ?MarkerColorScale: StyleParam.Colorscale * ?MarkerOutline: Line * ?MarkerSymbol: StyleParam.MarkerSymbol * ?MultiMarkerSymbol: StyleParam.MarkerSymbol seq * ?Marker: TraceObjects.Marker * ?Below: string * ?EnableClustering: bool * ?Cluster: MapboxCluster * ?UseDefaults: bool -> GenericChart (requires 'c :> System.IConvertible)
static member Chart.PointMapbox: longitudesEncoded: EncodedTypedArray * latitudesEncoded: EncodedTypedArray * ?Name: string * ?MapboxStyle: StyleParam.MapboxStyle * ?ShowLegend: bool * ?Opacity: float * ?MultiOpacity: float seq * ?Text: 'a * ?MultiText: 'a seq * ?TextPosition: StyleParam.TextPosition * ?MultiTextPosition: StyleParam.TextPosition seq * ?MarkerColor: Color * ?MarkerColorScale: StyleParam.Colorscale * ?MarkerOutline: Line * ?MarkerSymbol: StyleParam.MarkerSymbol * ?MultiMarkerSymbol: StyleParam.MarkerSymbol seq * ?Marker: TraceObjects.Marker * ?Below: string * ?EnableClustering: bool * ?Cluster: MapboxCluster * ?UseDefaults: bool -> GenericChart (requires 'a :> System.IConvertible)
static member Chart.PointMapbox: longitudes: #System.IConvertible seq * latitudes: #System.IConvertible seq * ?Name: string * ?MapboxStyle: StyleParam.MapboxStyle * ?ShowLegend: bool * ?Opacity: float * ?MultiOpacity: float seq * ?Text: 'c * ?MultiText: 'c seq * ?TextPosition: StyleParam.TextPosition * ?MultiTextPosition: StyleParam.TextPosition seq * ?MarkerColor: Color * ?MarkerColorScale: StyleParam.Colorscale * ?MarkerOutline: Line * ?MarkerSymbol: StyleParam.MarkerSymbol * ?MultiMarkerSymbol: StyleParam.MarkerSymbol seq * ?Marker: TraceObjects.Marker * ?Below: string * ?EnableClustering: bool * ?Cluster: MapboxCluster * ?UseDefaults: bool -> GenericChart (requires 'c :> System.IConvertible)

static member Chart.withMapbox: mapbox: Mapbox * ?Id: int -> (GenericChart -> GenericChart)

type GenericChart = | Chart of data: Trace * layout: Layout * config: Config * displayOpts: DisplayOptions | MultiChart of data: Trace list * layout: Layout * config: Config * displayOpts: DisplayOptions static member addConfig: config: Config -> gChart: GenericChart -> GenericChart static member addDisplayOptions: displayOpts: DisplayOptions -> gChart: GenericChart -> GenericChart static member addLayout: layout: Layout -> gChart: GenericChart -> GenericChart static member combine: gCharts: GenericChart seq -> GenericChart static member countTrace: gChart: GenericChart -> int static member existsTrace: predicate: (Trace -> bool) -> gChart: GenericChart -> bool static member fromChartDTO: dto: ChartDTO -> GenericChart static member fromFigure: fig: Figure -> GenericChart static member getConfig: gChart: GenericChart -> Config static member getDisplayOptions: gChart: GenericChart -> DisplayOptions ...
<summary> The central type that gets created by all Chart constructors is GenericChart, which itself represents either a single chart or a multi chart (as a Discriminate Union type). A GenericChart consists of four top level objects: Trace (multiple of those in the case of a MultiChart), Layout, Config, and DisplayOptions. - `Trace` is in principle the representation of a dataset on a chart, including for example the data itself, color and shape of the visualization, etc. - `Layout` is everything of the chart that is not dataset specific - e.g. the shape and style of axes, the chart title, etc. - `Config` is an object that configures high level properties of the chart like making all chart elements editable or the tool bar on top - `DisplayOptions` is an object that contains meta information about how the html document that contains the chart. </summary>

static member GenericChart.toChartHTML: gChart: GenericChart -> string

val mbWithToken: Mapbox

Multiple items
val string: value: 'T -> string

--------------------
type string = System.String