# Map of the United States by 3-digit ZIP code area, one number per area, with the state borders

A chartlink template (choropleth). Page: https://chartlink.app/maps/us/zip-codes · Example image: https://chartlink.app/a/ast_NHq9NO5IqJlAhHMKV7iHO.png?v=20&w=1200 · Template id: `ast_NHq9NO5IqJlAhHMKV7iHO`

Also answers: US ZIP code map · map by ZIP prefix · colour ZIP code areas by a value · nationwide ZIP choropleth · ZIP-level data map of America

## About

Data: one row per 3-digit ZIP prefix (902 for Los Angeles — keep leading zeros, so 010 not 10) and a number. 5-digit ZIP codes must be grouped to their first three digits first. An area with no row stays grey; white gaps inside the map are land with no ZIP code at all (parks, military land, desert). State borders are drawn on top. Same design as the state and county maps, so the three can sit side by side.

A choropleth map of the 3-digit ZIP code areas of the United States (894 areas, with Alaska, Hawaii and Puerto Rico as insets), each region filled by one number from your data (the "income" column). The borders of the US states and Puerto Rico are drawn on top of the regions in dark navy blue, 0.5 units wide, so the finer regions read inside their larger units.

A sequential colour scale from pale blue for the smallest values to deep navy blue for the largest; pinned to 40000 to 150000, so values beyond the ends take the end colour and the colour bar says ≤ and ≥; a gradient colour bar below the map, with its labels underneath; values formatted as USD amounts, in compact form (1.2k, 3.4M), 0 decimals; on a white canvas (#ffffff) with near-black text — a light theme; 0.25-unit hairline outlines between regions.

The title and description are left-aligned above the chart. Font: Inter (the default); a source line with a link sits at the bottom, with the chartlink badge in the corner.

Data: 2 columns — zip3 (string, "ZIP prefix (3 digits)"), income (number, "Average AGI per return ($)") — and 885 rows in the example "Average income per tax return by ZIP code area, 2021". Regions are named by 3-digit ZIP prefixes; a region with no row stays unfilled in grey, and an unknown code fails loudly with the nearest matches. Your data keeps the same column ids and every other setting comes from the template; an agent can change any of them.

Other looks of this template — dark (on a dark canvas): ast_RKYYARDuhlCOgVXMQfOY5; buckets (with the values in classes and a swatch legend): ast_cmOusTs2UUwFtRicLBEZ8; editorial (in the editorial house style — serif type on paper, a green ramp): ast_R66eT2CnHqEhneYI14KnD; categories (with a text category per region and a swatch legend): ast_tP4BaVIpYAKUwllIOBPrE; buckets-dark (with the values in classes and a swatch legend, on a dark canvas): ast_Pi94QyowwscyYLq4KoXrg; surroundings (with the land around the place drawn in grey): ast_raf98DNuLhq0IbzZSjOTo; categories-dark (with a text category per region and a swatch legend, on a dark canvas): ast_IXkcayIce7TYivC9Bn3bm; buckets-editorial (with the values in classes and a swatch legend, in the editorial house style — serif type on paper, a green ramp): ast_1CqAlkmvPswfgGh4kNKEX; dark-surroundings (on a dark canvas, with the land around the place drawn in grey): ast_NRauNeskb3KfCNZLCapwu; buckets-surroundings (with the values in classes and a swatch legend, with the land around the place drawn in grey): ast_Ut2TKbOrCdGP6ew13vfV0; categories-editorial (with a text category per region and a swatch legend, in the editorial house style — serif type on paper, a green ramp): ast_dyDmWvYyeFT5EDJdaxisl; editorial-surroundings (in the editorial house style — serif type on paper, a green ramp, with the land around the place drawn in grey): ast_RhnHae4ES5YdnZRQ1xR84; categories-surroundings (with a text category per region and a swatch legend, with the land around the place drawn in grey): ast_IftHCFZ6y2K1xKFXJlpXj; buckets-dark-surroundings (with the values in classes and a swatch legend, on a dark canvas, with the land around the place drawn in grey): ast_zIHCtcaLQPZhMSUTBJH51; categories-dark-surroundings (with a text category per region and a swatch legend, on a dark canvas, with the land around the place drawn in grey): ast_iNmKxJvWc9R3yU7DGXxTO; buckets-editorial-surroundings (with the values in classes and a swatch legend, in the editorial house style — serif type on paper, a green ramp, with the land around the place drawn in grey): ast_ihhjcN2AhvSx5FeOVegDy; categories-editorial-surroundings (with a text category per region and a swatch legend, in the editorial house style — serif type on paper, a green ramp, with the land around the place drawn in grey): ast_1ujWFvIrm5YzsgPTDZjn4. On the page, switch with the toggles; an agent passes that id as the template instead.

## Looks

Available: gradient light, gradient dark, buckets light, gradient editorial, categories light, buckets dark, gradient light with surroundings, categories dark, buckets editorial, gradient dark with surroundings, buckets light with surroundings, categories editorial, gradient editorial with surroundings, categories light with surroundings, buckets dark with surroundings, categories dark with surroundings, buckets editorial with surroundings, categories editorial with surroundings. Pick one with the `theme`, `dataType` and `surroundings` knobs.

## Knobs (the template's settings)

- `theme`: "light" | "dark" | "editorial" (default "light") — light or dark: the whole colour bundle — canvas, text, outlines, key (editorial: the house style, where a template offers it — the contract's looks say)
- `dataType`: "gradient" | "buckets" | "categories" (default "gradient") — How the value column is encoded. "gradient": a number per region on a continuous scale. "buckets": numbers sorted into classes with a swatch key. "categories": a TEXT label per region, one colour each
- `surroundings`: boolean (default false) — true draws the land around the place in quiet grey — the neighbouring states or countries — and the water in blue, so the reader sees where it sits. The frame stays the same. With it, waterColor and landColor apply.
- `missing`: "hatch" | "plain" — How a region with no row is drawn: "hatch" (thin diagonal lines, the templates' default) or "plain" (a flat grey)
- `waterColor`: string — With surroundings: the colour of the water (the map area's ground). An error without surroundings: true
- `landColor`: string — With surroundings: the fill of the neighbouring land. An error without surroundings: true
- `backgroundColor`: string — Overrides the canvas colour after the theme; text and outline colours stay the theme's
- `border`: object — A frame around the whole graphic
- `title`: object
- `description`: object
- `source`: object — The source line at the bottom left
- `brand`: object — The byline at the bottom right — premium charts only; the free tier reads "Made with chartlink.app"
- `colormap`: "blues" | "greens" | "purples" | "oranges" | "reds" | "greys" | "yellow-green-blue" | "yellow-orange-red" | "viridis" | "magma" | "cividis" | "blue-red" | "red-blue" | "brown-teal" | "purple-green" | "orange-purple" — gradient and buckets: the colour ramp. One hue: blues (default), greens, purples, oranges, reds, greys. Several hues: yellow-green-blue, yellow-orange-red, viridis, magma, cividis. Diverging around zero, for signed data: blue-red, red-blue, brown-teal, purple-green, orange-purple. Details: blues (the default: one blue, light to dark); greens (one green, light to dark); purples (one purple, light to dark); oranges (one orange, light to dark); reds (one red, light to dark); greys (one grey, light to dark — for a muted map); yellow-green-blue (pale yellow through green to deep blue (ColorBrewer YlGnBu)); yellow-orange-red (pale yellow through orange to deep red (ColorBrewer YlOrRd) — heat); viridis (dark purple through teal to yellow — perceptually even, colour-blind safe); magma (black through magenta to pale yellow — perceptually even); cividis (blue to yellow — even and safe for every kind of colour blindness); blue-red (blue below zero, red above (the default diverging)); red-blue (red below zero, blue above); brown-teal (brown below, teal above (ColorBrewer BrBG) — dry against wet, loss against gain); purple-green (purple below, green above (ColorBrewer PRGn)); orange-purple (orange below, purple above (ColorBrewer PuOr))
- `direction`: "normal" | "reversed" — gradient and buckets: "reversed" runs the colormap the other way — dark for low values, or the arms of a diverging ramp swapped — when a high number is the bad one
- `range`: array — gradient (and equal-width buckets): pin the scale to [min, max]; values beyond clamp and the key says ≤ / ≥ — an outlier no longer pushes every other region to one end. Omit to fit the data
- `breaks`: array — buckets: the ascending cut points between classes; sets the class count
- `classes`: integer — buckets: how many quantile classes when breaks are not given (default 5)
- `categoryColors`: object — categories: a colour per label, e.g. {"Republican": "#dc2626"}
- `categoryOrder`: array — categories: the key's order; labels not listed follow in order of appearance

## Data

| column | role | type | about |
|---|---|---|---|
| `zip3` | region | string | The region, as a code the geography knows (see region) |
| `income` | value | number | The value per region: a number for gradient and buckets, a text label for categories |

## Region codes

Geography `us-zip3`: 3-digit ZIP prefixes. The region's exact name or a listed alias also works; unknown codes fail with the closest matches.. A region with no row stays grey.
Examples: `006` (006), `481` (481), `999` (999).
Every region with its aliases: https://chartlink.app/api/geographies/us-zip3

## What each dataType expects

- **gradient**: value column number; knobs `colormap`, `direction`, `range`. A continuous colour scale fitted to your numbers; colormap names the ramp (blues by default; a diverging one pins its middle to zero), direction reverses it, range pins the ends so an outlier cannot stretch the scale.
- **buckets**: value column number; knobs `colormap`, `direction`, `breaks`, `classes`, `range`. Numbers sorted into classes with a swatch key: give breaks, or a class count (quantiles by default; with range, equal-width); colormap and direction as for gradient.
- **categories**: value column string; knobs `categoryColors`, `categoryOrder`. A label per region, one colour each, keyed in the order the labels first appear (or categoryOrder).

## With surroundings

With surroundings: true the water and the neighbouring land are drawn; these two knobs recolour them. Without it they are an error. Knobs: `waterColor`, `landColor`.

## Make one

Copy this shape, replace the rows with yours, and POST it (no account needed: `POST /api/signup` returns a key, shown once).

```
POST https://chartlink.app/api/assets
Authorization: Bearer <apiKey>
{
  "template": "ast_NHq9NO5IqJlAhHMKV7iHO",
  "knobs": {
    "theme": "light",
    "dataType": "gradient",
    "title": {
      "text": "Your title"
    },
    "description": {
      "text": "One sentence on what the map shows."
    },
    "source": {
      "text": "Where the numbers come from"
    }
  },
  "data": {
    "columns": [
      {
        "id": "zip3",
        "type": "string"
      },
      {
        "id": "income",
        "type": "number"
      }
    ],
    "rows": [
      [
        "010",
        78810
      ],
      [
        "011",
        64313
      ],
      [
        "012",
        83804
      ]
    ]
  },
  "publish": true
}
```

Dry run first if unsure of the codes: `POST https://chartlink.app/api/templates/map-us-zip/check` with {data, knobs} reports unmatched values with the closest real codes and creates nothing.

The create does this check itself: a region value that matches nothing comes back as a 400 listing it with the closest real codes, before anything is made. The template can be named by its id, its slug, or its page address (us/zip-codes).

Over MCP (`https://chartlink.app/mcp`): `list_templates` → `get_template` → `create_from_template` (`check_template_data` when you want the report without creating).

- POST https://chartlink.app/api/assets with the example's shape: template, knobs, your data (publish: true when it is final). Over MCP: create_from_template.
- A 201 means it validated and rendered; the response carries urls.embedIframe, urls.png and urls.page, and a preview to look at.
- Anything beyond the knobs is the advanced path: a config object, deep-merged after the knobs — the manual at /llms-full.txt.

## Similar templates

- Map of the United States by congressional district, one number per district, with the state borders: https://chartlink.app/templates/map-us-districts.md
- Map of the United States by county, one number per county, with the state borders: https://chartlink.app/templates/map-us-counties.md
- Map of the United States by metropolitan area, one number per metro, with the state borders: https://chartlink.app/templates/map-us-metros.md
- Map of the United States by state, one number per state: https://chartlink.app/templates/map-us-states.md
- Map of Wyoming by ZIP code, one number per ZIP code: https://chartlink.app/templates/map-us-wyoming-zip-codes.md
- Map of Wisconsin by ZIP code, one number per ZIP code: https://chartlink.app/templates/map-us-wisconsin-zip-codes.md
- Map of West Virginia by ZIP code, one number per ZIP code: https://chartlink.app/templates/map-us-west-virginia-zip-codes.md
- Map of Washington by ZIP code, one number per ZIP code: https://chartlink.app/templates/map-us-washington-zip-codes.md

All templates: https://chartlink.app/llms.txt · The engine behind them: https://chartlink.app/llms-full.txt