Black Lives Matter. Please consider donating to Black Girls Code today.

Mapbox Choropleth Maps in Python

How to make a Mapbox Choropleth Map of US Counties in Python with Plotly.

If you're using Dash Enterprise's Data Science Workspaces, you can copy/paste any of these cells into a Workspace Jupyter notebook.
Alternatively, download this entire tutorial as a Jupyter notebook and import it into your Workspace.
Find out if your company is using Dash Enterprise.

Install Dash Enterprise on Azure | Install Dash Enterprise on AWS

New to Plotly?

Plotly is a free and open-source graphing library for Python. We recommend you read our Getting Started guide for the latest installation or upgrade instructions, then move on to our Plotly Fundamentals tutorials or dive straight in to some Basic Charts tutorials.

A Choropleth Map is a map composed of colored polygons. It is used to represent spatial variations of a quantity. This page documents how to build tile-map choropleth maps, but you can also build outline choropleth maps using our non-Mapbox trace types.

Below we show how to create Choropleth Maps using either Plotly Express' px.choropleth_mapbox function or the lower-level go.Choroplethmapbox graph object.

Mapbox Access Tokens and Base Map Configuration

To plot on Mapbox maps with Plotly you may need a Mapbox account and a public Mapbox Access Token. See our Mapbox Map Layers documentation for more information.

Introduction: main parameters for choropleth tile maps

Making choropleth Mapbox maps requires two main types of input:

  1. GeoJSON-formatted geometry information where each feature has either an id field or some identifying value in properties.
  2. A list of values indexed by feature identifier.

The GeoJSON data is passed to the geojson argument, and the data is passed into the color argument of px.choropleth_mapbox (z if using graph_objects), in the same order as the IDs are passed into the location argument.

Note the geojson attribute can also be the URL to a GeoJSON file, which can speed up map rendering in certain cases.

GeoJSON with

Here we load a GeoJSON file containing the geometry information for US counties, where is a FIPS code.

In [1]:
from urllib.request import urlopen
import json
with urlopen('') as response:
    counties = json.load(response)

{'type': 'Feature',
 'properties': {'GEO_ID': '0500000US01001',
  'STATE': '01',
  'COUNTY': '001',
  'NAME': 'Autauga',
  'LSAD': 'County',
  'CENSUSAREA': 594.436},
 'geometry': {'type': 'Polygon',
  'coordinates': [[[-86.496774, 32.344437],
    [-86.717897, 32.402814],
    [-86.814912, 32.340803],
    [-86.890581, 32.502974],
    [-86.917595, 32.664169],
    [-86.71339, 32.661732],
    [-86.714219, 32.705694],
    [-86.413116, 32.707386],
    [-86.411172, 32.409937],
    [-86.496774, 32.344437]]]},
 'id': '01001'}

Data indexed by id

Here we load unemployment data by county, also indexed by FIPS code.

In [2]:
import pandas as pd
df = pd.read_csv("",
                   dtype={"fips": str})
fips unemp
0 01001 5.3
1 01003 5.4
2 01005 8.6
3 01007 6.6
4 01009 5.5

Choropleth map using and carto base map (no token needed)

Plotly Express is the easy-to-use, high-level interface to Plotly, which operates on a variety of types of data and produces easy-to-style figures.

With px.choropleth_mapbox, each row of the DataFrame is represented as a region of the choropleth.

In [3]:
from urllib.request import urlopen
import json
with urlopen('') as response:
    counties = json.load(response)

import pandas as pd
df = pd.read_csv("",
                   dtype={"fips": str})

import as px

fig = px.choropleth_mapbox(df, geojson=counties, locations='fips', color='unemp',
                           range_color=(0, 12),
                           zoom=3, center = {"lat": 37.0902, "lon": -95.7129},
                           labels={'unemp':'unemployment rate'}