doc/python/location-mode.md
With outline-based maps, you can visualize data for specific regions using the locations and locationmode parameters.
The following map types in plotly.express and plotly.graph_objects support these parameters:
px.choropleth - color regions based on data valuespx.scatter_geo - show markers at geographic locationspx.line_geo - draw lines connecting geographic locationsgo.Choropleth - choropleth trace for coloring regionsgo.Scattergeo - geographic scatter/line trace for markers and linesThe locations parameter accepts region identifiers and the locationmode parameter controls how those identifiers are interpreted:
'ISO-3' - three-letter ISO country codes (for example, 'USA', 'CAN', 'GBR')'USA-states' - two-letter US state abbreviations (for example, 'CA', 'TX', 'NY')'country names' - full country names (for example, 'United States')Set locationmode='ISO-3' to use three-letter ISO country codes in locations.
import plotly.express as px
fig = px.choropleth(
locations=['USA', 'CAN', 'MEX', 'BRA', 'RUS'],
locationmode='ISO-3',
color=[100, 85, 72, 95, 68],
color_continuous_scale='Viridis',
title='Choropleth with ISO-3 Country Codes'
)
fig.show()
The following ISO codes are supported when locationmode='ISO-3':
Set locationmode='USA-states' to use two-letter US state abbreviations in locations.
import plotly.express as px
fig = px.choropleth(
locations=['CA', 'TX', 'NY', 'FL', 'IL'],
locationmode='USA-states',
color=[95, 88, 92, 85, 78],
scope='usa',
color_continuous_scale='Reds',
title='USA States Choropleth'
)
fig.show()
The following state codes are supported when locationmode='USA-states':
Set locationmode='country names' to use full country names in locations.
import plotly.express as px
fig = px.choropleth(
locations=['United States', 'Canada', 'United Kingdom'],
locationmode='country names'
)
fig.show()
How Plotly matches 'country names' will change in a future version. Matching will become stricter and some country names may no longer match. We recommend using
locationmode='ISO-3'with ISO codes forlocationsto ensure consistent behavior across versions.
import plotly.express as px
fig = px.choropleth(
locations=['USA', 'CAN', 'GBR'],
locationmode='ISO-3'
)
fig.show()
locationsEarlier examples demonstrated using the locations parameter with Python lists. The locations parameter also accepts column names from DataFrames, pandas Series, or other array-like objects.
Here's an example that uses a column from the gapminder dataset with locations:
import plotly.express as px
df = px.data.gapminder().query("year == 2007")
fig = px.choropleth(
df,
locations='iso_alpha',
locationmode='ISO-3',
color='lifeExp',
hover_name='country',
color_continuous_scale='Viridis',
title='Life Expectancy by Country (2007)'
)
fig.show()