apexmaps-geo

Boundary geometry for ApexMaps: 26 TopoJSON packs covering world countries and coastline, US states and all 3,231 counties, EU NUTS levels 0 to 3, and admin-1 divisions for 15 more countries. Every pack carries its own provenance: source, licence, attribution, vintage and boundary policy.

You usually do not need to install this. ApexMaps fetches packs from jsDelivr on demand, so geo: { map: 'world/countries@110m' } works with nothing installed. Install this package when you want the files locally: offline development, an air-gapped deployment, a bundler that should resolve geometry at build time, or self-hosting.

npm install apexmaps-geo

Using it with ApexMaps

Point the library at the installed copy, and nothing hits the network:

import ApexMaps from 'apexmaps'

// Bundlers (Vite, webpack, Rollup, esbuild) resolve JSON imports natively.
ApexMaps.setGeoSource((file) => import(`apexmaps-geo/${file}`).then((m) => m.default))

In plain Node ESM, JSON needs an import attribute:

ApexMaps.setGeoSource((file) =>
  import(`apexmaps-geo/${file}`, { with: { type: 'json' } }).then((m) => m.default),
)

Self-hosting instead? Copy the files anywhere your server can reach and give setGeoSource a base URL:

ApexMaps.setGeoSource('/static/geo/')

Using it without ApexMaps

The files are ordinary TopoJSON, so nothing here is ApexMaps-specific:

import { feature } from 'topojson-client'
import topology from 'apexmaps-geo/world-countries-110m.json'

const countries = feature(topology, topology.objects.countries)

manifest.json lists every pack with the TopoJSON object name to convert, the feature count, the recommended join key, and full provenance:

{
  "id": "au/admin1@10m",
  "file": "au-admin1-10m.json",
  "object": "admin1",
  "features": 12,
  "keyField": "iso_3166_2",
  "levelName": "States",
  "source": "Natural Earth 5.1.1",
  "license": "public domain",
  "vintage": "2022"
}

Versioning

This dataset is versioned independently of the ApexMaps library, which is the reason it is a separate package. Boundaries change on their own schedule: NUTS is revised every three years, US counties re-district on the census, and countries rename themselves. A boundary correction should not require a library upgrade, and a library patch should not republish 6.8 MB of unchanged JSON.

The major version is a compatibility contract with the library, which requests apexmaps-geo@<major> by default:

• Patch releases fix a file without changing its identifier, feature count or keys.
• Minor releases add packs.
• Major releases rename or remove a pack id, change a recommended join key, or change the file layout. Pack ids are public API, so this is rare and deliberate.

Licences

This package is a compilation of separately licensed datasets, so terms apply per file. Full detail is in LICENSE; the short version:

| Files | Source | Licence | Attribution | |---|---|---|---| | world-*, *-admin1-* | Natural Earth 5.1.1 | Public domain | None required | | us-states-*, us-counties-* | US Census TIGER/Line, via us-atlas 3.0 | Public domain | None required | | eu-nuts* | Eurostat GISCO NUTS 2021 | CC BY 4.0, plus EuroGeographics terms | © EuroGeographics for the administrative boundaries |

The NUTS packs are the only ones carrying a mandatory attribution requirement. ApexMaps renders that string automatically whenever a NUTS pack is on screen, so using the library satisfies it for you. Using these files directly makes it your responsibility.

Boundary depiction follows each source's own editorial view and is not a political statement by the ApexCharts project.

Regenerating

These files are built from source by npm run data:build in the ApexMaps repository, which downloads the upstream data, simplifies and quantizes it, repairs identifiers, and writes manifest.json. The build fails if the packs it produces disagree with the pack ids declared in the library, because a catalogue entry with no file is a runtime 404 and a file with no entry is invisible.