@giving-tuesday/gt-geo

Geographic data for GivingTuesday visualizations: TopoJSON topologies, prejoined with the region names our charts match on, published to npm and served over jsDelivr.

It holds TopoJSON, not GeoJSON — consumers convert with topojson-client's feature(). There is no runtime code here; the package is a folder of data files addressed by URL.

https://cdn.jsdelivr.net/npm/@giving-tuesday/gt-geo@1/data/us-counties-states-10m.json

Why this is its own package

The geometry changes when its upstream source ships new boundaries, which is close to never. Consumers of it — embed-app, and eventually the gt-charts Python wrapper — release on their own, much faster cadences. Versioning the data with any one of them would republish an identical ~875 KB artifact on every patch and pin consumers to a version number that says nothing about the data.

The name contract

This is the package's public API, more than the files are. A choropleth joins its values to geometry by name: in ECharts, each series.data[].name must equal a feature's properties.name. The join is a string comparison with no fuzzy matching and no error when it fails — unmatched regions simply render unshaded.

So the name format is a contract, and changing it is a breaking change:

| Object | properties.name | Example | | --- | --- | --- | | counties | "<County>, <State>" | "Mohave, Arizona" | | states | "<State>" | "Arizona" | | nation | "<Nation>" | "United States" |

Note the county name carries no "County" suffix — it is upstream's bare name plus the state, joined on the first two digits of the county FIPS id. All 3,231 counties resolve to a state; none fall back to a bare name.

Datasets

| File | Objects | Regions | Size (gzip) | | --- | --- | --- | --- | | data/us-counties-states-10m.json | counties, states, nation | 3,231 / 56 / 1 | 875 KB (257 KB) |

Derived from us-atlas counties-10m, pinned to an exact upstream version in the generator so a rebuild is reproducible.

states includes the five inhabited territories (American Samoa, Guam, the Northern Mariana Islands, Puerto Rico, the US Virgin Islands) alongside the 50 states and DC. The albersUsa projection covers the 50 states and DC only — d3 returns no position for the territories, so their features silently do not render under it. That is a property of the projection, not of this data.

Using it

Pin the major version in the URL so you get geometry refreshes but never a name-contract change.

embed-app

<section
  data-embed
  data-type="EChart"
  data-uid="county-map"
  data-map-config='{
    "src": "https://cdn.jsdelivr.net/npm/@giving-tuesday/gt-geo@1/data/us-counties-states-10m.json",
    "topologyObjectName": "counties",
    "projection": "albersUsa"
  }'
  data-option='{"series":[{"type":"map","map":"USA","data":[{"name":"Mohave, Arizona","value":213267}]}]}'
></section>

Anything else

import { feature } from 'topojson-client';

const topology = await (
  await fetch('https://cdn.jsdelivr.net/npm/@giving-tuesday/gt-geo@1/data/us-counties-states-10m.json')
).json();
const counties = feature(topology, topology.objects.counties);

jsDelivr serves these with Access-Control-Allow-Origin: *, so a browser fetch needs no proxy and no bucket CORS configuration.

Versioning

SemVer, applied to the data rather than to code:

• major — the name contract changes, or an objects key is renamed or removed
• minor — a dataset is added, or an object is added to an existing one
• patch — geometry refreshed from upstream, names unchanged

A consumer pinned to @1 should never have a map go blank.

Working on it

npm ci
npm run build       # regenerate every dataset from upstream
npm run typecheck

Generated files are committed. The point of the repo is the data, so what ships should be reviewable in a diff and reproducible byte-for-byte — building at publish time would ship bytes nobody looked at. CI enforces the two match: it rebuilds and fails the release if data/ comes out different from what is committed.

Output is written minified on purpose. An editor that reformats it on save roughly doubles the file and produces an unreadable diff; .editorconfig and .prettierignore are there to prevent that.

Adding a dataset

1. Add scripts/<name>.mts that writes one file into data/, pinning its upstream source to an exact version.
2. Add a build:<name> script and chain it into build.
3. Document its properties.name format in The name contract above — that table is what consumers code against.
4. Release as a minor.

Releasing

Tag-driven, same as the other GivingTuesday packages:

npm version minor && git push --follow-tags

Or run the Publish workflow manually and pick a bump. Either way CI verifies data/ before publishing to public npm, which is what makes the files available on jsDelivr. (jsDelivr does not serve GitHub Packages, so this package is unscoped and public.)

Attribution & license

County and state geometry is derived from us-atlas (ISC, © Mike Bostock), itself built from US Census Bureau cartographic boundary files, which are in the public domain.

This package is ISC licensed; see LICENSE.