Plotly · Function

px.choropleth

Creates an interactive outline choropleth map, coloring geographic polygons according to supplied values. It supports built-in country and US-state geometries as well as custom GeoJSON boundaries.

How it works

px.choropleth builds an interactive outline-based map by associating geographic identifiers with numeric values and mapping those values to polygon colors. Identifiers can refer to built-in countries or states, or to features in supplied GeoJSON; the resulting figure uses Plotly's geographic layout.

Syntax

plotly.express.choropleth(data_frame=None, lat=None, lon=None, locations=None, locationmode=None, geojson=None, featureidkey='id', color=None, hover_name=None, hover_data=None, custom_data=None, animation_frame=None, animation_group=None, category_orders=None, labels=None, color_discrete_sequence=None, color_discrete_map=None, color_continuous_scale=None, range_color=None, color_continuous_midpoint=None, opacity=None, facet_row=None, facet_col=None, facet_col_wrap=None, facet_row_spacing=None, facet_col_spacing=None, facet_col_wrap=None, hover_name=None, hover_data=None, title=None, template=None, width=None, height=None, projection=None, scope=None, center=None, fitbounds=None, basemap_visible=None, **kwargs)

Parameters

Name	Type	Description
`data_frame`	`DataFrame or array-like`	Data frame or array-like data source containing the plotted values and location fields.
`locations`	`str or array-like`	Geographic identifiers or the name of a data-frame column containing them.
`color`	`str or array-like`	Values or the name of a data-frame column used to color regions.
`geojson`	`dict or str`	GeoJSON geometry defining custom geographic features.
`locationmode`	`str`	Interpretation mode for location identifiers, such as ISO-3, USA-states, or country names.
`scope`	`str`	Geographic view to display, such as usa or world.
`color_continuous_scale`	`str or list`	Color scale used for numeric values.
`**kwargs`	`keyword arguments`	Additional Plotly Express and figure-layout options.

Returns

A Plotly graph_objects.Figure containing a choropleth trace and geographic layout.

Key points

The function represents geographic regions as polygons whose fill colors encode data values.
Use it when the main comparison is how a numeric measure varies across locations.
Custom geographic boundaries can be provided through the geojson argument.
The function can use Plotly's built-in geometries for world countries and US states.
For custom geometry, provide GeoJSON separately from the tabular values.
The color argument supplies the quantitative field or sequence used for the color scale.
US state abbreviations are supported when locationmode is set to USA-states.

Common mistakes

When using custom GeoJSON, the feature identifiers and data locations must correspond; mismatches can prevent regions from receiving the intended values.
Choose locationmode to match the identifier format; ISO-3 is for three-letter country codes, not arbitrary names.

Example: Country choropleth using ISO-3 codes

import plotly.express as px

fig = px.choropleth(
    locations=["USA", "CAN", "MEX"],
    locationmode="ISO-3",
    color=[100, 85, 72],
    color_continuous_scale="Viridis",
    title="Values by country",
)
fig.show()

Creates an interactive outline map whose country colors represent the supplied values.

When to use it

World-country comparisons

Color countries by a metric such as population, rate, or index.

US state analysis

Display values for states using abbreviations or full state names.

Custom GeoJSON regions

Visualize administrative or statistical boundaries not included by Plotly.

Animated geographic data

Show how a regional metric changes between time periods.

Interview questions

QWhat does px.choropleth visualize?

px.choropleth creates an outline map made of colored polygons. It combines geographic geometry with values supplied through color, then uses locations to associate each value with a region.

Follow-up: How would you use custom boundaries? Pass GeoJSON through geojson, identify its features with locations, and ensure the feature identifiers align with those locations.

QHow are geographic locations specified?

Use locations for region identifiers and locationmode to define how Plotly interprets them. For example, locationmode='ISO-3' makes values such as USA and CAN represent countries.

Follow-up: How would you map US states? Use state identifiers with locationmode='USA-states' and typically set scope='usa' for the geographic view.

QWhat inputs are required for a choropleth?

Built-in geometries support countries and US states, while custom regions can be supplied as GeoJSON. The color argument provides the numeric values that determine each region's color.

Follow-up: What must be true for custom GeoJSON data to work? Each GeoJSON feature needs an identifier, or an identifying value in its properties, that matches the values used in locations.

px.choropleth_map
go.Choropleth
px.scatter_geo
px.line_geo
layout.geo

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