Mapbox Maps vs Geo Maps

Binder  Script  Notebook

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 Geo outline-based maps, and the Mapbox Layers documentation describes how to configure Mapbox tile-based maps.

Physical Base Maps

Plotly Geo maps have a built-in base map layer composed of "physical" and "cultural" (i.e. administrative border) data from the Natural Earth Dataset. Various lines and area fills can be shown or hidden, and their color and line-widths specified. In the default plotly template, a map frame and physical features such as a coastal outline and filled land areas are shown, at a small-scale 1:110m resolution:

open Plotly.NET

let baseMapOnly =
    Chart.PointGeo(locations = []) // deliberately empty chart to show the base map only
    |> Chart.withMarginSize (0, 0, 0, 0)

To control the features of the map, a Geo object is used that can be associated with a given chart using the Chart.WithGeo function. Here is a map with all physical features enabled and styled, at a larger-scale 1:50m resolution:

open Plotly.NET.LayoutObjects

let myGeo =
    Geo.init (
        Resolution = StyleParam.GeoResolution.R50,
        ShowCoastLines = true,
        CoastLineColor = Color.fromString "RebeccaPurple",
        ShowLand = true,
        LandColor = Color.fromString "LightGreen",
        ShowOcean = true,
        OceanColor = Color.fromString "LightBlue",
        ShowLakes = true,
        LakeColor = Color.fromString "Blue",
        ShowRivers = true,
        RiverColor = Color.fromString "Blue"
    )

let moreFeaturesBaseMap =
    Chart.PointGeo(locations = [])
    |> Chart.withGeo myGeo
    |> Chart.withMarginSize (0, 0, 0, 0)

Cultural Base Maps

In addition to physical base map features, a "cultural" base map is included which is composed of country borders and selected sub-country borders such as states.

Note and disclaimer: cultural features are by definition subject to change, debate and dispute. Plotly includes data from Natural Earth "as-is" and defers to the Natural Earth policy regarding disputed borders which read:

Natural Earth Vector draws boundaries of countries according to defacto status. We show who actually controls the situation on the ground.

Here is a map with only cultural features enabled and styled, at a 1:50m resolution, which includes only country boundaries. See below for country sub-unit cultural base map features:

let countryGeo =
    Geo.init (
        Visible = false,
        Resolution = StyleParam.GeoResolution.R50,
        ShowCountries = true,
        CountryColor = Color.fromString "RebeccaPurple"
    )


let countryBaseMap =
    Chart.PointGeo(locations = [])
    |> Chart.withGeo countryGeo
    |> Chart.withMarginSize (0, 0, 0, 0)
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: DisplayOptions
Multiple items
type DisplayOptions = inherit DynamicObj new: unit -> DisplayOptions static member addAdditionalHeadTags: additionalHeadTags: XmlNode list -> (DisplayOptions -> DisplayOptions) static member addDescription: description: XmlNode list -> (DisplayOptions -> DisplayOptions) static member combine: first: DisplayOptions -> second: DisplayOptions -> DisplayOptions static member getAdditionalHeadTags: displayOpts: DisplayOptions -> XmlNode list static member getDescription: displayOpts: DisplayOptions -> XmlNode list static member getPlotlyReference: displayOpts: DisplayOptions -> PlotlyJSReference static member init: ?AdditionalHeadTags: XmlNode list * ?Description: XmlNode list * ?PlotlyJSReference: PlotlyJSReference -> DisplayOptions static member initCDNOnly: unit -> DisplayOptions ...

--------------------
new: unit -> DisplayOptions
static member DisplayOptions.init: ?AdditionalHeadTags: Giraffe.ViewEngine.HtmlElements.XmlNode list * ?Description: Giraffe.ViewEngine.HtmlElements.XmlNode list * ?PlotlyJSReference: PlotlyJSReference -> 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 PlotlyJSReference.NoReference: PlotlyJSReference
val baseMapOnly: GenericChart.GenericChart
type Chart = static member AnnotatedHeatmap: zData: seq<#seq<'a1>> * annotationText: seq<#seq<string>> * ?Name: string * ?ShowLegend: bool * ?Opacity: float * ?X: seq<'a3> * ?MultiX: seq<seq<'a3>> * ?XGap: int * ?Y: seq<'a4> * ?MultiY: seq<seq<'a4>> * ?YGap: int * ?Text: 'a5 * ?MultiText: seq<'a5> * ?ColorBar: ColorBar * ?ColorScale: Colorscale * ?ShowScale: bool * ?ReverseScale: bool * ?ZSmooth: SmoothAlg * ?Transpose: bool * ?UseWebGL: bool * ?ReverseYAxis: bool * ?UseDefaults: bool -> GenericChart (requires 'a1 :> IConvertible and 'a3 :> IConvertible and 'a4 :> IConvertible and 'a5 :> IConvertible) + 1 overload static member Area: x: seq<#IConvertible> * y: seq<#IConvertible> * ?ShowMarkers: bool * ?Name: string * ?ShowLegend: bool * ?Opacity: float * ?MultiOpacity: seq<float> * ?Text: 'a2 * ?MultiText: seq<'a2> * ?TextPosition: TextPosition * ?MultiTextPosition: seq<TextPosition> * ?MarkerColor: Color * ?MarkerColorScale: Colorscale * ?MarkerOutline: Line * ?MarkerSymbol: MarkerSymbol * ?MultiMarkerSymbol: seq<MarkerSymbol> * ?Marker: Marker * ?LineColor: Color * ?LineColorScale: Colorscale * ?LineWidth: float * ?LineDash: DrawingStyle * ?Line: Line * ?AlignmentGroup: string * ?OffsetGroup: string * ?StackGroup: string * ?Orientation: Orientation * ?GroupNorm: GroupNorm * ?FillColor: Color * ?FillPatternShape: PatternShape * ?FillPattern: Pattern * ?UseWebGL: bool * ?UseDefaults: bool -> GenericChart (requires 'a2 :> IConvertible) + 1 overload static member Bar: values: seq<#IConvertible> * ?Keys: seq<'a1> * ?MultiKeys: seq<seq<'a1>> * ?Name: string * ?ShowLegend: bool * ?Opacity: float * ?MultiOpacity: seq<float> * ?Text: 'a2 * ?MultiText: seq<'a2> * ?MarkerColor: Color * ?MarkerColorScale: Colorscale * ?MarkerOutline: Line * ?MarkerPatternShape: PatternShape * ?MultiMarkerPatternShape: seq<PatternShape> * ?MarkerPattern: Pattern * ?Marker: Marker * ?Base: #IConvertible * ?Width: 'a4 * ?MultiWidth: seq<'a4> * ?TextPosition: TextPosition * ?MultiTextPosition: seq<TextPosition> * ?UseDefaults: bool -> GenericChart (requires 'a1 :> IConvertible and 'a2 :> IConvertible and 'a4 :> IConvertible) + 1 overload static member BoxPlot: ?X: seq<'a0> * ?MultiX: seq<seq<'a0>> * ?Y: seq<'a1> * ?MultiY: seq<seq<'a1>> * ?Name: string * ?ShowLegend: bool * ?Text: 'a2 * ?MultiText: seq<'a2> * ?FillColor: Color * ?MarkerColor: Color * ?Marker: Marker * ?Opacity: float * ?WhiskerWidth: float * ?BoxPoints: BoxPoints * ?BoxMean: BoxMean * ?Jitter: float * ?PointPos: float * ?Orientation: Orientation * ?OutlineColor: Color * ?OutlineWidth: float * ?Outline: Line * ?AlignmentGroup: string * ?OffsetGroup: string * ?Notched: bool * ?NotchWidth: float * ?QuartileMethod: QuartileMethod * ?UseDefaults: bool -> GenericChart (requires 'a0 :> IConvertible and 'a1 :> IConvertible and 'a2 :> IConvertible) + 2 overloads static member Bubble: x: seq<#IConvertible> * y: seq<#IConvertible> * sizes: seq<int> * ?Name: string * ?ShowLegend: bool * ?Opacity: float * ?MultiOpacity: seq<float> * ?Text: 'a2 * ?MultiText: seq<'a2> * ?TextPosition: TextPosition * ?MultiTextPosition: seq<TextPosition> * ?MarkerColor: Color * ?MarkerColorScale: Colorscale * ?MarkerOutline: Line * ?MarkerSymbol: MarkerSymbol * ?MultiMarkerSymbol: seq<MarkerSymbol> * ?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 'a2 :> IConvertible) + 1 overload static member Candlestick: ``open`` : seq<#IConvertible> * high: seq<#IConvertible> * low: seq<#IConvertible> * close: seq<#IConvertible> * ?X: seq<'a4> * ?MultiX: seq<seq<'a4>> * ?Name: string * ?ShowLegend: bool * ?Opacity: float * ?Text: 'a5 * ?MultiText: seq<'a5> * ?Line: Line * ?IncreasingColor: Color * ?Increasing: FinanceMarker * ?DecreasingColor: Color * ?Decreasing: FinanceMarker * ?WhiskerWidth: float * ?ShowXAxisRangeSlider: bool * ?UseDefaults: bool -> GenericChart (requires 'a4 :> IConvertible and 'a5 :> IConvertible) + 2 overloads static member Column: values: seq<#IConvertible> * ?Keys: seq<'a1> * ?MultiKeys: seq<seq<'a1>> * ?Name: string * ?ShowLegend: bool * ?Opacity: float * ?MultiOpacity: seq<float> * ?Text: 'a2 * ?MultiText: seq<'a2> * ?MarkerColor: Color * ?MarkerColorScale: Colorscale * ?MarkerOutline: Line * ?MarkerPatternShape: PatternShape * ?MultiMarkerPatternShape: seq<PatternShape> * ?MarkerPattern: Pattern * ?Marker: Marker * ?Base: #IConvertible * ?Width: 'a4 * ?MultiWidth: seq<'a4> * ?TextPosition: TextPosition * ?MultiTextPosition: seq<TextPosition> * ?UseDefaults: bool -> GenericChart (requires 'a1 :> IConvertible and 'a2 :> IConvertible and 'a4 :> IConvertible) + 1 overload static member Contour: zData: seq<#seq<'a1>> * ?Name: string * ?ShowLegend: bool * ?Opacity: float * ?X: seq<'a2> * ?MultiX: seq<seq<'a2>> * ?Y: seq<'a3> * ?MultiY: seq<seq<'a3>> * ?Text: 'a4 * ?MultiText: seq<'a4> * ?ColorBar: ColorBar * ?ColorScale: Colorscale * ?ShowScale: bool * ?ReverseScale: bool * ?Transpose: bool * ?ContourLineColor: Color * ?ContourLineDash: DrawingStyle * ?ContourLineSmoothing: float * ?ContourLine: Line * ?ContoursColoring: ContourColoring * ?ContoursOperation: ConstraintOperation * ?ContoursType: ContourType * ?ShowContourLabels: bool * ?ContourLabelFont: Font * ?Contours: Contours * ?FillColor: Color * ?NContours: int * ?UseDefaults: bool -> GenericChart (requires 'a1 :> IConvertible and 'a2 :> IConvertible and 'a3 :> IConvertible and 'a4 :> IConvertible) static member Funnel: x: seq<#IConvertible> * y: seq<#IConvertible> * ?Name: string * ?ShowLegend: bool * ?Opacity: float * ?Width: float * ?Offset: float * ?Text: 'a2 * ?MultiText: seq<'a2> * ?TextPosition: TextPosition * ?MultiTextPosition: seq<TextPosition> * ?Orientation: Orientation * ?AlignmentGroup: string * ?OffsetGroup: string * ?MarkerColor: Color * ?MarkerOutline: Line * ?Marker: Marker * ?TextInfo: TextInfo * ?ConnectorLineColor: Color * ?ConnectorLineStyle: DrawingStyle * ?ConnectorFillColor: Color * ?ConnectorLine: Line * ?Connector: FunnelConnector * ?InsideTextFont: Font * ?OutsideTextFont: Font * ?UseDefaults: bool -> GenericChart (requires 'a2 :> IConvertible) static member Heatmap: zData: seq<#seq<'a1>> * ?X: seq<'a2> * ?MultiX: seq<seq<'a2>> * ?Y: seq<'a3> * ?MultiY: seq<seq<'a3>> * ?Name: string * ?ShowLegend: bool * ?Opacity: float * ?XGap: int * ?YGap: int * ?Text: 'a4 * ?MultiText: seq<'a4> * ?ColorBar: ColorBar * ?ColorScale: Colorscale * ?ShowScale: bool * ?ReverseScale: bool * ?ZSmooth: SmoothAlg * ?Transpose: bool * ?UseWebGL: bool * ?ReverseYAxis: bool * ?UseDefaults: bool -> GenericChart (requires 'a1 :> IConvertible and 'a2 :> IConvertible and 'a3 :> IConvertible and 'a4 :> IConvertible) + 1 overload ...
static member Chart.PointGeo: locations: seq<string> * ?Name: string * ?ShowLegend: bool * ?Opacity: float * ?MultiOpacity: seq<float> * ?Text: 'a * ?MultiText: seq<'a> * ?TextPosition: StyleParam.TextPosition * ?MultiTextPosition: seq<StyleParam.TextPosition> * ?MarkerColor: Color * ?MarkerColorScale: StyleParam.Colorscale * ?MarkerOutline: Line * ?MarkerSymbol: StyleParam.MarkerSymbol * ?MultiMarkerSymbol: seq<StyleParam.MarkerSymbol> * ?Marker: TraceObjects.Marker * ?LocationMode: StyleParam.LocationFormat * ?GeoJson: obj * ?FeatureIdKey: string * ?UseDefaults: bool -> GenericChart.GenericChart (requires 'a :> System.IConvertible)
static member Chart.PointGeo: lonlat: seq<#System.IConvertible * #System.IConvertible> * ?Name: string * ?ShowLegend: bool * ?Opacity: float * ?MultiOpacity: seq<float> * ?Text: 'a2 * ?MultiText: seq<'a2> * ?TextPosition: StyleParam.TextPosition * ?MultiTextPosition: seq<StyleParam.TextPosition> * ?MarkerColor: Color * ?MarkerColorScale: StyleParam.Colorscale * ?MarkerOutline: Line * ?MarkerSymbol: StyleParam.MarkerSymbol * ?MultiMarkerSymbol: seq<StyleParam.MarkerSymbol> * ?Marker: TraceObjects.Marker * ?LocationMode: StyleParam.LocationFormat * ?GeoJson: obj * ?FeatureIdKey: string * ?UseDefaults: bool -> GenericChart.GenericChart (requires 'a2 :> System.IConvertible)
static member Chart.PointGeo: longitudes: seq<#System.IConvertible> * latitudes: seq<#System.IConvertible> * ?Name: string * ?ShowLegend: bool * ?Opacity: float * ?MultiOpacity: seq<float> * ?Text: 'a2 * ?MultiText: seq<'a2> * ?TextPosition: StyleParam.TextPosition * ?MultiTextPosition: seq<StyleParam.TextPosition> * ?MarkerColor: Color * ?MarkerColorScale: StyleParam.Colorscale * ?MarkerOutline: Line * ?MarkerSymbol: StyleParam.MarkerSymbol * ?MultiMarkerSymbol: seq<StyleParam.MarkerSymbol> * ?Marker: TraceObjects.Marker * ?LocationMode: StyleParam.LocationFormat * ?GeoJson: obj * ?FeatureIdKey: string * ?UseDefaults: bool -> GenericChart.GenericChart (requires 'a2 :> System.IConvertible)
static member Chart.withMarginSize: ?Left: 'a * ?Right: 'b * ?Top: 'c * ?Bottom: 'd * ?Pad: 'e * ?Autoexpand: 'f -> (GenericChart.GenericChart -> GenericChart.GenericChart)
module GenericChart from Plotly.NET
<summary> Module to represent a GenericChart </summary>
val toChartHTML: gChart: GenericChart.GenericChart -> string
namespace Plotly.NET.LayoutObjects
val myGeo: Geo
Multiple items
type Geo = inherit DynamicObj new: unit -> Geo static member init: ?FitBounds: GeoFitBounds * ?Resolution: GeoResolution * ?Scope: GeoScope * ?Projection: GeoProjection * ?Center: (float * float) * ?Visible: bool * ?Domain: Domain * ?ShowCoastLines: bool * ?CoastLineColor: Color * ?CoastLineWidth: float * ?ShowLand: bool * ?LandColor: Color * ?ShowOcean: bool * ?OceanColor: Color * ?ShowLakes: bool * ?LakeColor: Color * ?ShowRivers: bool * ?RiverColor: Color * ?RiverWidth: float * ?ShowCountries: bool * ?CountryColor: Color * ?CountryWidth: float * ?ShowSubunits: bool * ?SubunitColor: Color * ?SubunitWidth: float * ?ShowFrame: bool * ?FrameColor: Color * ?FrameWidth: float * ?BgColor: Color * ?LatAxis: LinearAxis * ?LonAxis: LinearAxis -> Geo static member style: ?FitBounds: GeoFitBounds * ?Resolution: GeoResolution * ?Scope: GeoScope * ?Projection: GeoProjection * ?Center: (float * float) * ?Visible: bool * ?Domain: Domain * ?ShowCoastLines: bool * ?CoastLineColor: Color * ?CoastLineWidth: float * ?ShowLand: bool * ?LandColor: Color * ?ShowOcean: bool * ?OceanColor: Color * ?ShowLakes: bool * ?LakeColor: Color * ?ShowRivers: bool * ?RiverColor: Color * ?RiverWidth: float * ?ShowCountries: bool * ?CountryColor: Color * ?CountryWidth: float * ?ShowSubunits: bool * ?SubunitColor: Color * ?SubunitWidth: float * ?ShowFrame: bool * ?FrameColor: Color * ?FrameWidth: float * ?BgColor: Color * ?LatAxis: LinearAxis * ?LonAxis: LinearAxis -> (Geo -> Geo)
<summary>Determines the style of the map shown in geo traces</summary>

--------------------
new: unit -> Geo
static member Geo.init: ?FitBounds: StyleParam.GeoFitBounds * ?Resolution: StyleParam.GeoResolution * ?Scope: StyleParam.GeoScope * ?Projection: GeoProjection * ?Center: (float * float) * ?Visible: bool * ?Domain: Domain * ?ShowCoastLines: bool * ?CoastLineColor: Color * ?CoastLineWidth: float * ?ShowLand: bool * ?LandColor: Color * ?ShowOcean: bool * ?OceanColor: Color * ?ShowLakes: bool * ?LakeColor: Color * ?ShowRivers: bool * ?RiverColor: Color * ?RiverWidth: float * ?ShowCountries: bool * ?CountryColor: Color * ?CountryWidth: float * ?ShowSubunits: bool * ?SubunitColor: Color * ?SubunitWidth: float * ?ShowFrame: bool * ?FrameColor: Color * ?FrameWidth: float * ?BgColor: Color * ?LatAxis: LinearAxis * ?LonAxis: LinearAxis -> Geo
module StyleParam from Plotly.NET
type GeoResolution = | R110 | R50 member Convert: unit -> obj override ToString: unit -> string static member convert: (GeoResolution -> obj) static member toString: (GeoResolution -> string)
<summary> Used for the Layout.geo field. Sets the resolution of the base layers. The values have units of km/mm e.g. 110 corresponds to a scale ratio of 1:110,000,000. </summary>
union case StyleParam.GeoResolution.R50: StyleParam.GeoResolution
type Color = override Equals: other: obj -> bool override GetHashCode: unit -> int static member fromARGB: a: int -> r: int -> g: int -> b: int -> Color static member fromColorScaleValues: c: seq<#IConvertible> -> Color static member fromColors: c: seq<Color> -> Color static member fromHex: s: string -> Color static member fromKeyword: c: ColorKeyword -> Color static member fromRGB: r: int -> g: int -> b: int -> Color static member fromString: c: string -> Color member Value: obj
<summary> Plotly color can be a single color, a sequence of colors, or a sequence of numeric values referencing the color of the colorscale obj </summary>
static member Color.fromString: c: string -> Color
val moreFeaturesBaseMap: GenericChart.GenericChart
static member Chart.withGeo: geo: Geo * ?Id: int -> (GenericChart.GenericChart -> GenericChart.GenericChart)
val countryGeo: Geo
val countryBaseMap: GenericChart.GenericChart