Plotly · Class

go.Choropleth

go.Choropleth creates an outline-based choropleth trace, coloring geographic polygons from numeric z values. Use locations with a matching locationmode, and configure the surrounding geographic subplot through layout.geo.

How it works

Construct a Choropleth trace with region identifiers in locations and numeric values in z. Plotly colors each region according to z, while locationmode determines how identifiers are interpreted; the trace is displayed within a geo subplot whose appearance can be configured through layout.geo.

Syntax

go.Choropleth(arg=None, autocolorscale=None, coloraxis=None, colorbar=None, colorscale=None, featureidkey=None, geo=None, geojson=None, hoverinfo=None, hovertemplate=None, locations=None, locationmode=None, marker=None, name=None, reversescale=None, showlegend=None, showscale=None, text=None, uid=None, uirevision=None, visible=None, z=None, zauto=None, zmax=None, zmid=None, zmin=None, **kwargs)

Parameters

Name	Type	Description
`locations`	`array`	Region identifiers used to select the geographic polygons.
`locationmode`	`string`	Interpretation scheme for values in locations, such as ISO-3 codes.
`z`	`array`	Numeric values that determine each region's color.
`geojson`	`object`	Optional GeoJSON geometry or feature data for custom regions.
`featureidkey`	`string`	Attribute path used to match locations to GeoJSON features.
`colorscale`	`array or string`	Color scale used to convert z values into polygon colors.

Returns

A Choropleth trace object for use in a Plotly figure.

Key points

Choropleth represents regional data by filling geographic polygons with colors.
Use it when the main comparison is how a numeric measure varies across places.
go.Choropleth is the graph-object API for direct trace construction and fine-grained control.
For outline maps, locations identifies regions and locationmode defines the identifier convention.
ISO-3 location mode lets locations contain three-letter country codes.
Configure the surrounding geographic base map through the figure's layout.geo object.

Common mistakes

Ensure that locations uses identifiers compatible with locationmode; otherwise regions will not match as intended.

Example: Basic outline choropleth

import plotly.graph_objects as go

fig = go.Figure(go.Choropleth(
    locations=["USA", "CAN", "MEX"],
    locationmode="ISO-3",
    z=[10, 20, 15],
    colorscale="Viridis",
    colorbar_title="Value"
))
fig.update_layout(geo=dict(scope="north america"))
fig.show()

Creates an outline choropleth by matching ISO-3 region codes in locations with numeric z values, then displays the figure.

When to use it

Regional comparisons

Compare a statistic across countries or other standard geographic regions.

Spatial variation

Show where a measure is high or low across a geographic area.

Custom-region mapping

Color custom geographic features from a GeoJSON file.

Interview questions

QWhat are the core inputs to go.Choropleth?

A Choropleth trace colors geographic polygons according to numeric values supplied through z. The regions come from locations, and locationmode specifies how those identifiers should be interpreted.

Follow-up: How would you use custom geographic regions? Supply GeoJSON through geojson and identify the matching GeoJSON feature field with featureidkey, while keeping locations aligned with those identifiers.

QHow do you map ISO country codes?

Use locationmode="ISO-3" when locations contains three-letter ISO country codes. The official outline-map guidance identifies locationmode as the control for interpreting region identifiers.

Follow-up: What other identifier scheme could be used? Choose a locationmode supported by the trace and provide locations in exactly that scheme, or use custom GeoJSON matching.

QWhere do you configure the map surrounding a Choropleth trace?

The trace uses the layout.geo object for base-map configuration. Because go.Choropleth is an outline-based geographic trace, settings such as the geographic scope and fit behavior belong under layout.geo.

Follow-up: How can the automatic initial extent be overridden? Set layout.geo.fitbounds explicitly, for example to false, and configure the desired geographic view separately.

plotly.graph_objects.Figure
go.layout.Geo
px.choropleth
go.Scattergeo

Source: Choropleth maps in Python. Checked 2026-10-15.