Plotly Geographic Maps

Geographic data visualization transforms rows of location-based information into intuitive, interactive maps that reveal patterns, trends, and outliers invisible in raw tables. For data scientists, the ability to create these maps efficiently is crucial for spatial analysis, from tracking global health metrics to visualizing regional sales performance. Plotly Express provides a high-level, declarative syntax to build powerful interactive maps with just a few lines of Python code, making sophisticated geospatial storytelling accessible.

Core Concepts for Geographic Visualization

The foundation of mapping with Plotly Express lies in understanding which function to use for your specific data and goal. The three primary functions—px.choropleth(), px.scatter_geo(), and px.scatter_mapbox()—each serve distinct purposes, and choosing correctly is the first step to an effective visualization.

Choropleth Maps for Regional Aggregates are created using px.choropleth(). This function shades predefined geographic regions—like countries, states, or counties—based on a numerical value associated with each region. It's ideal for showing how a measurement, such as GDP, population density, or election results, varies across a territory. The key parameters are locations, which expects a list of region identifiers (e.g., country names, state abbreviations), and color, which is set to the column containing the values that determine the shading. For example, a choropleth map of U.S. unemployment rates would use state codes for locations and the unemployment percentage column for color.

Point Maps for Discrete Locations are built with px.scatter_geo(). This function places markers (points) on a map based on latitude and longitude coordinates. It is perfect for visualizing the distribution of specific events or entities, such as earthquake epicenters, store locations, or city populations. You must provide lat and lon parameters with your coordinate data. The size parameter can make the markers proportional to a value, like the magnitude of an earthquake, creating a bubble map. This allows you to encode two data dimensions: location and a quantitative size.

High-Detail Tile-Based Maps require px.scatter_mapbox(). While scatter_geo uses Plotly's built-in base maps, scatter_mapbox leverages the Mapbox tileset service, which offers highly detailed, customizable, and performant map layers, including streets, satellite imagery, and terrain. This is the tool for creating complex, publication-quality maps or working with dense urban data. It uses the same lat and lon parameters as scatter_geo but requires you to set a Mapbox access token (available for free) via plotly.express.set_mapbox_access_token().

Integrating GeoJSON for Custom Boundaries

Plotly's built-in country and state boundaries will not cover every use case, such as mapping sales territories, watershed districts, or postal codes. This is where GeoJSON integration becomes essential. A GeoJSON file is a standard format for encoding geographic structures. You can supply a custom GeoJSON object to the geojson parameter in px.choropleth() and use the featureidkey parameter to specify the property within that GeoJSON file (e.g., "properties.district_id") that links to your dataframe's locations column. This powerful technique allows you to create choropleth maps for any geographic boundary system you have data for, from school districts to custom sales regions.

Mastering Aesthetics and Interactivity

With your base map created, controlling its appearance is key to clear communication. Custom color scales are set using the color_continuous_scale parameter. Instead of the default "Viridis," you can choose from Plotly's built-in sequential scales like "Plasma" or "Blues," or even define a custom list of colors. For categorical data mapped with color_discrete_sequence, you can define a set of distinct colors. The range_color parameter is critical for fair comparisons, as it locks the minimum and maximum values of the color scale across different views or animations, preventing misinterpretation.

Animation over time adds a powerful dimension for showing trends. By using the animation_frame parameter and pointing it to a column in your dataframe that represents time (e.g., "Year"), Plotly will create a slider and play button. Each frame shows the map state for a different time period, dynamically updating the colors or point positions. This is incredibly effective for visualizing the spread of a phenomenon, like a disease outbreak or the adoption of a technology, across years or months.

Building Interactive Geographic Dashboards

A single map is useful, but the true power of Plotly is realized when you integrate multiple maps and charts into an interactive geographic data exploration dashboard. Using the Plotly Dash framework, you can create a web application where selections on one component filter others. For instance, clicking a country on a global choropleth could update a time-series chart showing that country's historical data. You can add dropdowns to switch between different data metrics (color), or radio buttons to toggle between a choropleth and a scatter map view of the same data. This transforms your visualization from a static exhibit into an analytical tool for deep, user-driven exploration.

Common Pitfalls

1. Location Code Mismatches: The most common error in creating choropleth maps is a mismatch between your dataframe's location identifiers and Plotly's expected codes. Plotly expects ISO-3 codes (e.g., 'USA', 'FRA') for countries and two-letter state codes for the U.S. Using full names ("United States") will fail. Always verify your location column matches one of Plotly's built-in location modes or aligns perfectly with your custom GeoJSON's featureidkey.

1. Ignoring Map Projections: All maps distort the Earth's spherical surface. Plotly defaults to the Equirectangular projection, which is simple but can exaggerate the size of regions near the poles. For global data, consider setting projection="natural earth" in scatter_geo or choropleth for a more balanced view. For regional maps, "conic conformal" or "mercator" might be more appropriate. Choosing the wrong projection can mislead your audience.

1. Overwhelming Scatter Maps: When using px.scatter_geo() or px.scatter_mapbox() with thousands of points, the default result can be a cluttered, unreadable "hairball" of markers. Mitigate this by using the opacity parameter to create transparency, allowing density to show through. For Mapbox maps, use clustering by adding cluster=True to the scatter_mapbox call, which automatically groups nearby points and displays the count.

1. Poor Color Scale Choices: Using a sequential color scale (like "Viridis") for categorical data, or a diverging scale (like "RdBu") for purely positive data, confuses the message. Match the data type to the scale type: sequential for low-to-high values, diverging for data with a meaningful central point (like zero or an average), and categorical/discrete for distinct groups. Always test how your map looks in grayscale to ensure it's interpretable.

Summary

• Use px.choropleth() to create shaded region maps for aggregated data tied to geographic boundaries, linking your data via location codes or a custom GeoJSON file.
• Employ px.scatter_geo() for placing markers at specific latitude/longitude coordinates, ideal for discrete events or locations, and use px.scatter_mapbox() for high-detail, tile-based visualizations requiring a Mapbox token.
• Integrate custom GeoJSON data to map any boundary system not natively supported by Plotly, using the featureidkey to create the correct data-to-geometry link.
• Control interpretation by strategically setting color_continuous_scale and range_color, and add a temporal dimension seamlessly with the animation_frame parameter.
• Combine maps with other Plotly charts in an interactive dashboard to enable deep, user-driven geographic data exploration and hypothesis testing.