Offline OpenStreetMap map files for Action Stations:
one PMTiles vector file per US state, the District of
Columbia and each territory (PR, VI, GU, AS, MP), plus a catalog.json that lists them.
The map view in Action Stations uses these files so a tabletop exercise can show street maps with no internet connection. OpenStreetMap's own tile servers do not allow bulk or offline downloads, and Protomaps asks apps not to pull from its build server, so the files are cut here once a month and served from GitHub release assets.
The app reads https://github.com/actionstations-ai/maps/releases/latest/download/catalog.json
only when the user opens Download a state map or clicks Check for updates. Each catalog
entry gives the state's size, SHA-256, bounds and zoom range. The app downloads the file, checks the
SHA-256, then installs it. Nothing else in the app contacts this repository.
| Release | Contents |
|---|---|
YYYY-MM (for example 2026-11) |
The state files built that month and catalog.json |
latest |
A copy of the newest catalog.json (stable address) |
A state file is named us-<code>.pmtiles (us-oh.pmtiles). GitHub limits a release file to 2 GiB.
If a state is larger at zoom 15, the script lowers the maximum zoom (14, 13, 12), and as a last
resort splits the state into us-<code>-1.pmtiles and -2.pmtiles (west and east halves); the
catalog entry then lists both parts. The catalog records the real size, SHA-256, bounds and zoom
range of each file.
{
"formatVersion": 1,
"release": "2026-11",
"generatedAt": "2026-11-03T05:30:00.000Z",
"source": { "name": "...", "build": "20261103", "url": "https://docs.protomaps.com/basemaps/downloads" },
"license": "ODbL-1.0",
"attribution": "© OpenStreetMap contributors (ODbL 1.0) · Basemap data by Protomaps",
"entries": [
{
"id": "us-dc", "name": "District of Columbia", "kind": "district",
"bbox": [-77.1198, 38.7916, -76.9094, 38.9951], "minZoom": 0, "maxZoom": 15,
"parts": [{ "url": "https://github.com/.../us-dc.pmtiles", "bytes": 16657613, "sha256": "..." }]
}
]
}kind is state, district or territory. A run for only some states keeps the other entries
from the previous catalog.
- Map data is derived from OpenStreetMap, © OpenStreetMap contributors, available under the Open Database Licence (ODbL) 1.0. Anyone who uses these files must credit "© OpenStreetMap contributors" and keep the same licence on a database derived from them. See https://www.openstreetmap.org/copyright.
- Basemap tiles are built by Protomaps from OpenStreetMap (downloads). Show "Protomaps" with the OSM credit where space allows.
- State outlines used for the cuts are the US Census Bureau cartographic boundary files
(1:500,000), which are public domain, simplified and stored in
data/states.geojson. - Scripts and workflow in this repository are MIT licensed (
LICENSE).
Each file keeps its attribution in its own PMTiles metadata, and the app shows it on the map.
Needs Node.js 20 or newer and the pmtiles command.
npm test # unit tests for the helpers
node scripts/extract.mjs --out out --tag 2026-11 --states DC # one state, 8 seconds, ~17 MB
node scripts/catalog.mjs --dir out --tag 2026-11 # writes out/catalog.json
scripts/build-boundaries.sh # rebuild data/states.geojson (rarely)extract.mjs finds the newest build at https://build.protomaps.com/YYYYMMDD.pmtiles (from
https://build-metadata.protomaps.dev/builds.json); pass --build 20261103.pmtiles to pin one.
Leave out --states to build every region; this takes a few hours.
.github/workflows/build-maps.yml runs on the 3rd of each month and on demand (Actions tab, Run
workflow, optional state filter such as DC or OH,PA). It runs on a standard GitHub-hosted
runner, uses no artifacts or caches, uploads each state to the YYYY-MM release as it finishes, then
publishes catalog.json to that release and to latest.
Issues are disabled here; report problems in the Action Stations repository.