Proportional geographic bubbles
Compare population or another magnitude across countries or regions.
Plotly · Function
px.scatter_geo
px.scatter_geo creates an outline-map scatter plot where each data-frame row becomes a geographic marker. Columns can control marker location, color, size, and hover content.
How it works
px.scatter_geo constructs a Plotly figure containing geographic marker points from a data frame. Coordinates can come from latitude and longitude columns, or locations can be interpreted using a location mode; additional columns control color, size, labels, animation, and other visual properties.
Syntax
plotly.express.scatter_geo(data_frame=None, lat=None, lon=None, locations=None, locationmode=None, color=None, text=None, hover_name=None, hover_data=None, custom_data=None, size=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, size_max=None, projection=None, scope=None, center=None, fitbounds=None, basemap_visible=None, title=None, template=None, width=None, height=None)Parameters
| Name | Type | Description |
|---|---|---|
data_frame | DataFrame or array-like | Data frame containing the variables used to construct the plot. |
locations | str or array-like | Column or values supplying geographic location identifiers. |
lat | str or array-like | Column or values containing latitude coordinates. |
lon | str or array-like | Column or values containing longitude coordinates. |
color | str or array-like | Column or values controlling marker color. |
size | str or array-like | Column or values controlling marker size. |
hover_name | str or array-like | Column or values used for prominent hover labels. |
projection | str | Map projection name. |
Returns
A plotly.graph_objects.Figure containing a geographic scatter trace and geo-map layout.
Key points
- Each input row becomes one geographic marker.
- Map a numeric column to
sizeto create proportional marker bubbles. - The generated figure exposes geo-layout configuration for the underlying outline map.
Common mistakes
- For GeoPandas input, use point geometries or provide their extracted latitude and longitude values.
Example: Population by country on a world map
import plotly.express as px
df = px.data.gapminder().query("year == 2007")
fig = px.scatter_geo(
df,
locations="iso_alpha",
color="continent",
hover_name="country",
size="pop",
projection="natural earth",
)
fig.show()Creates an outline-based geographic scatter plot with country markers colored by continent and sized by population.
When to use it
Point-feature mapping
Display point observations from a GeoPandas data frame.
Animated spatial analysis
Explore geographic change across years or categories.
Interview questions
QWhat does px.scatter_geo represent?
It creates a geographic scatter plot in which each data-frame row becomes a marker. The map is an outline-based geo subplot, and marker properties can be mapped from columns such as color and size.
Follow-up: How would you plot a GeoPandas point data set? Supply latitude and longitude from the point geometry, then pass those values through lat and lon, optionally using a name column for hover text.
QHow can geographic positions be supplied?
Use locations when values identify geographic entities, such as country codes, and select the matching interpretation with locationmode when needed. Use lat and lon when the data already contains coordinates.
Follow-up: When would coordinates be preferable? They are preferable for arbitrary point features that do not correspond to the built-in geographic location identifiers.
QHow is the map appearance controlled?
The returned figure contains a go.layout.Geo object that controls the base map. Configure it with layout-geo settings, and choose a projection such as natural earth through the function arguments.
Follow-up: What lower-level trace corresponds to this chart? go.Scattergeo is the graph-object trace compatible with geo subplots and supports geographic markers, lines, curves, and filled areas.
Related
px.line_geopx.choroplethgo.Scattergeogo.layout.Geolayout.geo