DEV Community: ahmad-khan-97

Building a US choropleth in Python with plotly express, using a real fragrance dataset

ahmad-khan-97 — Thu, 14 May 2026 18:37:57 +0000

Plotly Express's choropleth is one of the cleanest "low-code, high-output" data viz tools in the Python ecosystem, but the documentation skips a few non-obvious gotchas that bite you the first time you build a US-state-level map. This walkthrough builds a publication-grade state map end-to-end, using a real dataset I open-sourced last week.

The dataset: the most-searched fragrance in every US state over the last 12 months, pulled from Google Trends across 30 of the most-talked-about fragrances of 2024-2026. Full dataset on GitHub under CC BY 4.0, full written analysis at perfumem.com.

What you'll build

A US state choropleth where each state is colored by its category winner (a discrete, not continuous, value), with a clean legend and a high-DPI export that's safe to drop into a blog post or report.

Setup

pip install plotly pandas kaleido

kaleido is the static image export engine; you need it if you want PNG output instead of just an interactive HTML chart.

Step 1: get the data into a clean DataFrame

If you want to follow along with the actual fragrance dataset:

import pandas as pd

df = pd.read_csv(
    "https://raw.githubusercontent.com/ahmad-khan-97/us-fragrance-trends-2026/main/data/winning_fragrance_per_state.csv"
)
print(df.head())
#         state         winning_fragrance  score      second_place  second_score
# 0     Alabama                 Old Spice     78         Polo Blue            61
# 1      Alaska         Coco Mademoiselle     71         Old Spice            66
# 2     Arizona                 Old Spice     82  Coco Mademoiselle            58

Wide format with one row per state and a categorical winner column. This is what plotly express's choropleth wants.

Step 2: map full state names to USPS codes (the gotcha)

plotly.express.choropleth with locationmode="USA-states" requires 2-letter USPS codes, not full state names. The most common silent failure mode is shipping a DataFrame with full names and getting an empty map with no error.

US_STATE_TO_CODE = {
    "Alabama": "AL", "Alaska": "AK", "Arizona": "AZ", "Arkansas": "AR",
    "California": "CA", "Colorado": "CO", "Connecticut": "CT", "Delaware": "DE",
    "District of Columbia": "DC", "Florida": "FL", "Georgia": "GA", "Hawaii": "HI",
    "Idaho": "ID", "Illinois": "IL", "Indiana": "IN", "Iowa": "IA",
    "Kansas": "KS", "Kentucky": "KY", "Louisiana": "LA", "Maine": "ME",
    "Maryland": "MD", "Massachusetts": "MA", "Michigan": "MI", "Minnesota": "MN",
    "Mississippi": "MS", "Missouri": "MO", "Montana": "MT", "Nebraska": "NE",
    "Nevada": "NV", "New Hampshire": "NH", "New Jersey": "NJ", "New Mexico": "NM",
    "New York": "NY", "North Carolina": "NC", "North Dakota": "ND", "Ohio": "OH",
    "Oklahoma": "OK", "Oregon": "OR", "Pennsylvania": "PA", "Rhode Island": "RI",
    "South Carolina": "SC", "South Dakota": "SD", "Tennessee": "TN", "Texas": "TX",
    "Utah": "UT", "Vermont": "VT", "Virginia": "VA", "Washington": "WA",
    "West Virginia": "WV", "Wisconsin": "WI", "Wyoming": "WY",
}

df["code"] = df["state"].map(US_STATE_TO_CODE)
missing = df[df["code"].isna()]
if len(missing) > 0:
    print("WARNING: unmapped states:", missing["state"].tolist())
df = df.dropna(subset=["code"])

Always check for unmapped rows. Google Trends sometimes returns territories like "Puerto Rico" or oddly capitalized "district of columbia" that won't match a strict dict lookup.

Step 3: build the choropleth

import plotly.express as px

fig = px.choropleth(
    df,
    locations="code",
    locationmode="USA-states",
    color="winning_fragrance",
    scope="usa",
    title="Most-searched fragrance by US state (Google Trends, 12mo)",
    color_discrete_sequence=px.colors.qualitative.Set3,
    hover_data={
        "state": True,
        "winning_fragrance": True,
        "score": True,
        "code": False,
    },
)

Three things that matter at this step:

color_discrete_sequence (not color_continuous_scale). When your fill variable is categorical (a fragrance name, a winning candidate, a product category), you want discrete colors. px.colors.qualitative.Set3 gives you 12 visually distinct colors that work well on choropleths. Other good options: Bold, Pastel, Vivid, Safe.
hover_data. By default, plotly shows the location code in hover, which reads as "AL" or "TX" and not as "Alabama" or "Texas". Override it explicitly so users see the full state name + the actual data point.
scope="usa". Without this, plotly draws the whole world map and shoves the US in one corner. With it, plotly auto-zooms and projects to USA Albers, which is the standard publication projection for US choropleths.

Step 4: clean up the layout

Default plotly titles and margins are conference-talk sized, which is too big for a blog post.

fig.update_layout(
    title=dict(
        text="Most-searched fragrance by US state",
        font=dict(size=22, family="Inter, system-ui, sans-serif"),
        x=0.5, xanchor="center",
    ),
    legend=dict(
        title="Top fragrance",
        font=dict(size=11),
        orientation="v",
        yanchor="middle", y=0.5,
        xanchor="left", x=1.02,
    ),
    geo=dict(
        bgcolor="rgba(0,0,0,0)",
        lakecolor="rgba(0,0,0,0)",
    ),
    margin=dict(l=10, r=10, t=80, b=20),
    paper_bgcolor="white",
)

Step 5: export at publication DPI

fig.write_image("us-state-map.png", width=1600, height=900, scale=2)

scale=2 doubles the effective DPI, giving you a sharp 3200x1800 raster. Anything less than scale=2 looks blurry on Retina displays in 2026.

For interactive HTML embed (Substack, Notion, blog post):

fig.write_html("us-state-map.html", include_plotlyjs="cdn", full_html=False)

full_html=False returns just the chart div, which you embed in an existing page. include_plotlyjs="cdn" keeps the file under 100 KB instead of the 4 MB you get with inline plotly.js.

Bonus: the matplotlib fallback for static-only PDF/print pipelines

If your downstream uses LaTeX or matplotlib-only figures (academic publishing, print magazines), here's the equivalent in pure matplotlib + geopandas:

import geopandas as gpd
import matplotlib.pyplot as plt

# US states shapefile (Census Bureau, public domain)
url = "https://www2.census.gov/geo/tiger/GENZ2021/shp/cb_2021_us_state_20m.zip"
states = gpd.read_file(url)
states = states.merge(df, left_on="STUSPS", right_on="code")

fig, ax = plt.subplots(figsize=(16, 9), dpi=200)
states.plot(
    column="winning_fragrance",
    ax=ax,
    legend=True,
    cmap="Set3",
    edgecolor="white",
    linewidth=0.5,
)
ax.set_xlim(-130, -65)  # crop to continental US
ax.set_ylim(23, 50)
ax.axis("off")
plt.tight_layout()
plt.savefig("us-state-map-mpl.png", dpi=200, bbox_inches="tight")

Slightly more code than plotly, but the output is print-ready and embeds cleanly into any LaTeX document.

What the data actually showed

Quick worked example using the dataset we just visualized:

Old Spice ranks #1 in 43 of 51 regions
8 outlier states pick something completely different:
- Alaska + South Dakota: Coco Mademoiselle (Chanel)
- Louisiana + Mississippi: Polo Blue (Ralph Lauren)
- Montana: Marc Jacobs Daisy
- New Mexico: Ariana Grande Cloud (the only state where Cloud ranks #1)
- North Dakota + Vermont: Glossier You

Two of those clusters (LA/MS, ND/VT) line up with broader regional consumer-brand patterns visible in other state-level datasets. The others are more interesting puzzles. Full interpretation is at perfumem.com.

Use this dataset for your own viz tutorials

The CSVs in this GitHub repo are CC BY 4.0. Drop them into any state-level viz tutorial you write, with attribution. Particularly useful for:

Choropleth tutorials (most state-level demo datasets are election or population, this gives you something different)
Categorical fill examples (winners, not magnitudes)
Cluster analysis on state-level consumer behavior
plotly.express vs geopandas head-to-head comparisons

What I'd improve in v2

Add a base map underlay. Choropleth-only maps lose context. A faint underlay of major cities + state borders would help readers locate Vermont vs New Hampshire vs Maine without squinting.
Animated time series version. plotly.express.choropleth with animation_frame= gives you a play button if you have monthly data. The fragrance dataset is annual, but if I re-pull monthly I could show how Glossier You took Vermont from Old Spice over time.
Highlight the outliers. Instead of equal coloring per state, dim the 43-state Old Spice block and highlight only the 8 outliers in vivid colors. This is the chart that should accompany the headline "8 states reject the national #1."

If you build any of these, link in the comments. The dataset is open under CC BY 4.0 so you only need to credit PerfumeM for the source data.

Source data + analysis: perfumem.com. Open dataset: github.com/ahmad-khan-97/us-fragrance-trends-2026 (CC BY 4.0).

I scraped Google Trends for 30 fragrances across all 50 US states with pytrends. 8 states reject the national #1.

ahmad-khan-97 — Thu, 14 May 2026 15:10:10 +0000

If you've used pytrends for the typical "trending this week" overview, you've probably hit the same wall I did: the default interest_over_time and trending_searches give you national-level signal, which is exactly what every other analyst already has. The interesting story is almost always at the regional level, and pytrends has a quietly underused method for that: interest_by_region(resolution="REGION").

I used it to answer a question that had been bugging me: when 30 of the most-talked-about fragrances of 2024-2026 are matched up across all 50 US states + DC, does every state pick the same #1, or do some go their own way?

Result: 43 states pick the same fragrance. 8 states pick something completely different, and the outliers cluster in ways that turned out to be defensible (more on this below).

The full analysis went up at perfumem.com, the raw CSVs and choropleth PNGs are on GitHub under CC BY 4.0. This post is the technical walkthrough, with the gotchas I had to work around.

The core pattern: pytrends batched at 5 keywords with a state-level resolution

pytrends accepts max 5 keywords per request. To analyze 30 fragrances across 50 states, you batch the keywords and stitch the wide matrix together yourself.

from pytrends.request import TrendReq
import pandas as pd
import time

FRAGRANCES = [
    "Dior Sauvage", "Bleu de Chanel", "Polo Blue", "Old Spice", "Glossier You",
    "Chanel No 5", "Coco Mademoiselle", "Marc Jacobs Daisy",
    "Ariana Grande Cloud", "Sol de Janeiro Cheirosa 62",
    # ... 20 more
]

BATCH_SIZE = 5
TIMEFRAME = "today 12-m"
GEO = "US"

pytrends = TrendReq(hl="en-US", tz=300, retries=3, backoff_factor=2)
rows = {}  # state -> {fragrance: score}

for i in range(0, len(FRAGRANCES), BATCH_SIZE):
    batch = FRAGRANCES[i:i + BATCH_SIZE]
    pytrends.build_payload(batch, timeframe=TIMEFRAME, geo=GEO)
    df = pytrends.interest_by_region(
        resolution="REGION",
        inc_low_vol=True,
        inc_geo_code=False,
    )
    for state, row in df.iterrows():
        rows.setdefault(state, {})
        for frag in batch:
            rows[state][frag] = int(row[frag])
    time.sleep(8)  # be polite, Google rate-limits aggressive callers

The output rows dict gives you a state x fragrance matrix you can pivot into anything.

Gotcha 1: Google's scores are relative, not absolute

This trips up almost everyone the first time. The 0-100 score is normalized within the keyword set you submitted in that batch. A score of 87 in batch A is not directly comparable to 87 in batch B unless you re-normalize.

The cleanest fix is to include a "calibration" keyword in every batch (something with stable, broad search volume) and renormalize relative to it. For my use case I skipped this because I wasn't comparing across batches: the per-state winner is just the highest score within each state's row, regardless of cross-batch absolute magnitude. If you need cross-batch comparability, factor in a calibration term.

# example: rebase each batch to a calibration keyword
CALIBRATION = "perfume"
batch_with_cal = [CALIBRATION] + batch[:4]  # 4 + 1 calibration
# after fetching, divide every score in batch by its calibration row score, multiply 100

Gotcha 2: `inc_low_vol=True` matters at the state level

Default is False, which means low-volume regions get filtered out and your matrix has holes. For a state-level analysis where some states (Wyoming, Alaska, Vermont) have low aggregate search activity, you want inc_low_vol=True or your sparse states disappear from the matrix entirely. Tradeoff: low-volume scores are noisier, so the bottom of the distribution is less trustworthy than the top.

Gotcha 3: pytrends is unmaintained-ish, expect occasional 429s

The project is community-maintained and Google occasionally changes the unofficial endpoint. Build retries with exponential backoff into your TrendReq constructor (retries=3, backoff_factor=2) and accept that some batches will need a re-run. I had 1 of my 6 batches fail on the first pass and had to retry an hour later.

Computing the per-state winner

Once you have the matrix, the winner-per-state is a one-liner:

import csv

with open("winners.csv", "w") as f:
    w = csv.writer(f)
    w.writerow(["state", "winning_fragrance", "score", "second_place", "second_score"])
    for state in sorted(rows.keys()):
        ranked = sorted(rows[state].items(), key=lambda kv: -kv[1])
        winner, score = ranked[0]
        second, second_score = (ranked[1] if len(ranked) > 1 else ("", 0))
        w.writerow([state, winner, score, second, second_score])

Visualizing it: choropleth in 30 lines with plotly

Plotly Express handles US state choropleths cleanly. The trick is mapping full state names to USPS 2-letter codes (which locationmode="USA-states" requires).

import plotly.express as px
import pandas as pd

US_STATE_TO_CODE = {
    "Alabama": "AL", "Alaska": "AK", "Arizona": "AZ", # ... (full dict)
}

df = pd.read_csv("winners.csv")
df["code"] = df["state"].map(US_STATE_TO_CODE)
df = df.dropna(subset=["code"])

fig = px.choropleth(
    df,
    locations="code",
    locationmode="USA-states",
    color="winning_fragrance",
    scope="usa",
    title="Most-searched fragrance by US state, last 12 months",
    color_discrete_sequence=px.colors.qualitative.Set3,
)
fig.write_image("us-state-map.png", width=1600, height=900, scale=2)

You'll need kaleido installed for write_image to work: pip install kaleido.

What the data actually showed

Old Spice ranks #1 in 43 states. Of the 8 outliers:

State	Winner	Category
Alaska, South Dakota	Coco Mademoiselle (Chanel)	Designer luxury women's
Louisiana, Mississippi	Polo Blue (Ralph Lauren)	Designer men's
Montana	Marc Jacobs Daisy	Designer women's
New Mexico	Ariana Grande Cloud	Celebrity / viral
North Dakota, Vermont	Glossier You	Niche / clean beauty

The clusters are interesting in ways I didn't expect going in. Louisiana + Mississippi sharing a #1 (Polo Blue) tracks with cultural Gulf Coast preference signals you can find in other consumer-goods data. North Dakota + Vermont sharing Glossier You was the strangest finding to me; both are low-population states with strong direct-to-consumer ecommerce penetration, and Glossier's brand voice plays well in both demographics, but I wouldn't have predicted them as a pair.

New Mexico is the only US state where Ariana Grande Cloud ranks #1, which is a "single state where a celebrity scent dominates" pattern that I'd love to see replicated for other celebrity fragrance launches.

Open data + reproducibility

Everything is on GitHub: ahmad-khan-97/us-fragrance-trends-2026. The repo includes:

data/raw_interest_by_state.csv: the full 30 x 51 matrix
data/winning_fragrance_per_state.csv: state, winner, score, runner-up, runner-up score
charts/: the three matplotlib + plotly outputs
LICENSE: CC BY 4.0, free to remix with attribution

The full written analysis with the cluster interpretation is at perfumem.com.

What I'd build next

If I were extending this:

Time series per state for the top 5 outlier picks: did Glossier You always win Vermont, or is this a 2026 phenomenon? interest_over_time per state would answer that.
Calibrated cross-state magnitude: with a calibration keyword in every batch, you could rank "intensity of fragrance interest" per state, not just the within-state winner.
Compare to actual purchase data: Google Trends measures search intent, not purchases. Anyone with a national fragrance retailer's POS data has a great cross-validation opportunity here.

If you build any of those, I'd love to see the result. The dataset is intentionally permissive (CC BY 4.0) so derivative analyses are encouraged.

Quick reference: the full minimal script

# us_state_fragrance_trends.py
from pytrends.request import TrendReq
import csv, time

FRAGRANCES = [...]  # your 5-30 keywords
BATCH_SIZE = 5

pytrends = TrendReq(hl="en-US", tz=300, retries=3, backoff_factor=2)
rows = {}

for i in range(0, len(FRAGRANCES), BATCH_SIZE):
    batch = FRAGRANCES[i:i + BATCH_SIZE]
    pytrends.build_payload(batch, timeframe="today 12-m", geo="US")
    df = pytrends.interest_by_region(resolution="REGION", inc_low_vol=True)
    for state, row in df.iterrows():
        rows.setdefault(state, {})
        for frag in batch:
            rows[state][frag] = int(row[frag])
    time.sleep(8)

with open("winners.csv", "w") as f:
    w = csv.writer(f)
    w.writerow(["state", "winner", "score"])
    for state, frag_scores in rows.items():
        winner, score = max(frag_scores.items(), key=lambda kv: kv[1])
        w.writerow([state, winner, score])

That's it. ~30 lines for a state-level Google Trends analysis you can drop any keyword set into.

If you build something with this pattern, drop a link in the comments. Particularly interested in non-fragrance domains: fast food, pickup trucks, streaming shows. The state-level segmentation usually reveals at least one cluster that the national ranking hides.

DEV Community: ahmad-khan-97

Building a US choropleth in Python with plotly express, using a real fragrance dataset

What you'll build

Setup

Step 1: get the data into a clean DataFrame

Step 2: map full state names to USPS codes (the gotcha)

Step 3: build the choropleth

Step 4: clean up the layout

Step 5: export at publication DPI

Bonus: the matplotlib fallback for static-only PDF/print pipelines

What the data actually showed

Use this dataset for your own viz tutorials

What I'd improve in v2

I scraped Google Trends for 30 fragrances across all 50 US states with pytrends. 8 states reject the national #1.

The core pattern: pytrends batched at 5 keywords with a state-level resolution

Gotcha 1: Google's scores are relative, not absolute

Gotcha 2: inc_low_vol=True matters at the state level

Gotcha 3: pytrends is unmaintained-ish, expect occasional 429s

Computing the per-state winner

Visualizing it: choropleth in 30 lines with plotly

What the data actually showed

Open data + reproducibility

What I'd build next

Quick reference: the full minimal script

Gotcha 2: `inc_low_vol=True` matters at the state level