According to the aggregated statistics, a choropleth map is a statistical map comprised of colored polygons. It is mainly applied in geographical areas, such as countries, states, counties, and postal codes.

When working with statistical analysis, you often encounter scenarios where you must plot a choropleth map.

Therefore, this article will discuss how you can create a choropleth Mapbox using Plotly’s graph_objects.


The choroplethmapbox() class from Plotl’y graph_objects allows us to create a Choroplethmapbox object with specific properties and customization.

The syntax is shown below:

class plotly.graph_objects.Choroplethmapbox(arg=None, autocolorscale=None, below=None, coloraxis=None, colorbar=None, colorscale=None, customdata=None, customdatasrc=None, featureidkey=None, geojson=None, hoverinfo=None, hoverinfosrc=None, hoverlabel=None, hovertemplate=None, hovertemplatesrc=None, hovertext=None, hovertextsrc=None, ids=None, idssrc=None, legendgroup=None, legendgrouptitle=None, legendrank=None, locations=None, locationssrc=None, marker=None, meta=None, metasrc=None, name=None, reversescale=None, selected=None, selectedpoints=None, showlegend=None, showscale=None, stream=None, subplot=None, text=None, textsrc=None, uid=None, uirevision=None, unselected=None, visible=None, z=None, zauto=None, zmax=None, zmid=None, zmin=None, zsrc=None, **kwargs)

The following are several essential properties you will use when using the Choroplethmapbox:

    1. Arg – specifies the properties of the choroplethmapbox object as a dictionary.
    2. Geojson – specifies the GeoJSON data associated with the choroplethmapbox.
    3. autocolorscale – sets the color scale palette, such as default or custom. This is a Boolean value.
    4. Geojson – specifies the GeoJSON data required for the choropleth trace. If no value is determined, Plotly will use the default base map.
    5. Locations – sets the coordinate using the location IDs or names.
    6. Locationmode – this parameter specifies the sets of locations used to match the entries in the location’s parameter.
    7. Colorscale – specifies the color scale as an RGB array.
    8. Hoverinfo – specifies the information that appears on the trace on mouse hover.
    9. Text – specifies the text elements that are associated with each location.
    10. Uid – assigns a unique ID of the choropleth trace.
    11. Z – specifies the color values.
    12. Name – specifies the choropleth trace name.
    13. Meta – provides extra metadata information associated with the Choropleth.
    14. Visible – sets if the choropleth object is visible or not.
    15. Ids – assigns a label to each column.

You will notice that it shares similar properties as a choropleth map.

Example 1

The following example illustrates how we can create a choroplethmapbox using the Choroplethmapbox class from Plotly’s graph_objects:

from urllib.request import urlopen
import json
import plotly.graph_objects as go
import pandas as pd
with urlopen('') as response:
    counties = json.load(response)

df = pd.read_csv("",
                   dtype={"fips": str})
fig = go.Figure(go.Choroplethmapbox(geojson=counties, locations=df.fips, z=df.unemp,
                                    colorscale="Reds", zmin=0, zmax=12,
                                    marker_opacity=0.5, marker_line_width=0), layout=dict(mapbox_style="carto-positron",
                  mapbox_zoom=3, mapbox_center = {"lat": 37, "lon": -95}))

In the previous example, we use the geojson data and fips unemp datasets from the Plotly datasets repo.

We then use the go.Figure function and pass the properties of the Choroplethmapbox in the go.Choroplethmapbox() class.

Note that we pass the layout properties as a dictionary. The previous code should return a figure as shown:

Example 2

You can customize your plot layout using the update_layout() function. For example, to switch the Mapbox layout to an open street map, you can run the following code:


The previous code should add a dark background with the set colorscale. The resulting plot is shown below:

Feel free to reference the documentation to learn about Choroplethmapbox properties and how you can use them with graph_objects.


This article provides a tutorial on how to create Choroplethmapbox using Plotly’s graph objects. In addition, several essential parameters were discussed when using the Choroplethmapbox:

About the author

John Otieno

My name is John and am a fellow geek like you. I am passionate about all things computers from Hardware, Operating systems to Programming. My dream is to share my knowledge with the world and help out fellow geeks. Follow my content by subscribing to LinuxHint mailing list