Skip to content
Tutorials Center
My learning

Topics

Lesson 29 of 42 ยท Maps and 3D

Geo Maps and Choropleths

Draw country and state maps in Plotly: choropleth with ISO codes, scattergeo points and lines, map projections, scope, fitbounds and styling of the geo layer.

Data about places is best shown on a map. Plotly has two families of maps. This lesson covers the geo family: outline maps drawn from built-in country and state shapes, with no internet tiles needed for the base map. The next lesson covers the tile-based street maps that zoom down to a single block.

The geo family gives you two core chart types:

  • Choropleth: regions (countries, states) filled with a color that encodes a value, such as population or election results.
  • Scattergeo: points, bubbles and lines placed by longitude and latitude, for cities, airports, routes and events.

A third, go.Scattergeo with mode="lines", draws paths such as flight routes. All three draw into a geo subplot, configured in layout.geo.

Choropleth by country

A choropleth needs two things per row: a location and a value. Locations are identified with locationmode:

  • "ISO-3" (default for px): three-letter country codes such as DEU, BRA, JPN.
  • "country names": full English names (convenient but less reliable).
  • "USA-states": two-letter US state codes such as TX.

With Plotly Express, px.choropleth(df, locations="iso_alpha", color="lifeExp") does it in one line. The built-in gapminder data already contains the iso_alpha column.

Python Life expectancy by country

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Set range_color yourself when you compare several maps (different years, for example), or each map picks its own scale and the colors lose meaning. Plotly draws the country shapes from a bundled topology file that the browser downloads on demand.

Here is a choropleth with a handful of countries written directly in Plotly.js. Countries without data stay in the base map color.

A hand-made choropleth (Plotly.js)

The geo layer: scope, projection and bounds

layout.geo controls everything about the base map. The options you will use most:

Property Meaning
scope "world", "usa", "europe", "asia", "africa", "north america", "south america"
projection.type "equirectangular", "mercator", "natural earth", "orthographic" (globe), "albers usa" and about 20 more
projection.rotation dict(lon=10, lat=40): where the globe is centered
fitbounds "locations" or "geojson": zoom to the data automatically
showcountries, showcoastlines, showland, showocean, showlakes, showrivers, showsubunits Which base layers to draw
landcolor, oceancolor, countrycolor, bgcolor Colors
resolution 110 (default) or 50 (finer coastlines, bigger download)

The orthographic projection shows the Earth as a rotatable globe, a nice effect for global data. "albers usa" is the classic choice for US maps because it moves Alaska and Hawaii to the bottom left.

px.choropleth is quick, but use a projection matched to your message. Mercator inflates countries near the poles (Greenland looks as large as Africa). For comparing area-like quantities, prefer "natural earth" or "equal earth"-style projections.

Scattergeo: cities, bubbles and routes

go.Scattergeo places markers by lon and lat (or by locations plus locationmode). Combine it with marker.size and marker.sizemode="area" to make a bubble map: the bubble's area, not its width, is proportional to the value, which is the honest way to scale.

Python Bubble map and a flight route

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Routes between two points are drawn along a great circle on most projections, so a London-Tokyo line curves over Russia on a flat map. That is correct, not a bug.

Custom shapes with GeoJSON

When your regions are not countries or US states (counties, postal districts, sales territories), supply the shapes yourself as GeoJSON and join them by id:

Python
fig = px.choropleth(df, geojson=counties_geojson, locations="fips", color="rate",
                    featureidkey="properties.GEOID", scope="usa")
fig.update_geos(fitbounds="locations", visible=False)

featureidkey tells Plotly which GeoJSON property matches your locations column. fitbounds="locations" zooms to the data, and visible=False hides the world base map so only your regions remain. A GeoJSON with many details can be several megabytes, so simplify the shapes (for example with mapshaper) before using them on a public web page.

Data pitfalls

  • Codes, not names. Joining on names invites mismatches ("Czechia" vs "Czech Republic"). Use ISO-3 codes.
  • Totals vs rates. A choropleth colors by area, so large, empty regions dominate visually. Show rates (per capita) rather than raw totals.
  • Missing regions simply stay unfilled. Mention it in the title or a note.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which locationmode do you use for two-letter US state codes?

    USA-states matches codes like TX or CA. ISO-3 expects three-letter country codes.
  2. 2. In a bubble map with sizemode="area", what is proportional to the value?

    Area scaling is the honest way to size circles because people read area, not diameter.
  3. 3. What does fitbounds="locations" do?

    fitbounds sets the visible map area from the data, which is ideal for custom GeoJSON regions.
  4. 4. Why should a choropleth usually show rates (per capita) instead of totals?

    Color fills the area of a region, so a totals map mostly shows population size. A rate makes regions comparable.

Summary

  • Geo maps draw from built-in shapes: Choropleth for filled regions, Scattergeo for points and routes.
  • Join regions with ISO-3 codes (locations) and set range_color to compare maps fairly.
  • layout.geo controls scope, projection, base layers, colors and fitbounds.
  • Use sizemode="area" for bubbles; use your own GeoJSON plus featureidkey for custom regions.
  • Map rates, not totals, and pick a projection that suits your message.

Next: Tile Maps and Density Maps