@john-guerra/geo-colombia

Colombia for data viz. d3 projections + ready-to-use departamento/municipio geometry, with independent subpath exports so you import only what you need.

• geoColombia — a base Transverse Mercator on Colombia's central meridian (like d3.geoAlbers for the US).
• geoColombiaComposite — an albersUsa-style composite that insets San Andrés y Providencia so they don't waste the frame on open sea (like d3.geoAlbersUsa does for Alaska & Hawaii).
• geoColombiaCompositeWorld — the composite plus a mini world inset in the SW corner for the diaspora (voto en el exterior): plot rest-of-world consulado features through .world().
• GeoJSON & TopoJSON of the 33 departamentos and 1 122 municipios (DANE / MGN).
• High-resolution San Andrés & Providencia coastlines.

Naming note: the npm package id is lowercase (@john-guerra/geo-colombia); the function exports are geoColombia / geoColombiaComposite.

Install

npm install @john-guerra/geo-colombia

Quick start

import { geoPath } from "d3-geo";
import { geoColombiaComposite, sanAndresProvidencia } from "@john-guerra/geo-colombia";
import departments from "@john-guerra/geo-colombia/geojson/departments" with { type: "json" };

// Fit to the MAINLAND so it centers and fills the frame; the islands tuck into the NW inset.
const mainland = { type: "FeatureCollection", features: departments.features.filter(d => d.properties.DPTO_CCDGO !== "88") };
const projection = geoColombiaComposite().fitExtent([[12, 12], [width - 12, height - 12]], mainland);
const path = geoPath(projection);

svg.append("path").attr("d", path(mainland));
svg.append("path").attr("d", path(sanAndresProvidencia)).attr("fill", "#CE742A");   // the islands (hi-res)
svg.append("path").attr("d", projection.getCompositionBorders()).attr("fill", "none").attr("stroke", "#888");

projection.invert([x, y]) works across all three sections, so hover/click hit-testing behaves over the islands too. See example/ for an interactive demo (dept ⇄ muni toggle + zoom): npm run example then open http://localhost:8099/example/.

Exports

| import | what | | --- | --- | | @john-guerra/geo-colombia | geoColombia, geoColombiaComposite, sanAndresProvidencia | | @john-guerra/geo-colombia/topojson | TopoJSON, objects MGN_ANM_DPTOS + MGN_ANM_MPIOS | | @john-guerra/geo-colombia/geojson/departments | GeoJSON FeatureCollection (33) | | @john-guerra/geo-colombia/geojson/municipalities | GeoJSON FeatureCollection (1 122) | | @john-guerra/geo-colombia/islands | sanAndresProvidencia (GeoJSON, hi-res) | | @john-guerra/geo-colombia/consulados | country name (UPPER) → ISO-3166 numeric, for the 67 overseas consulado units (join to a world TopoJSON by numeric id) |

Projection API

Both are standard d3 projections (.scale, .translate, .center via the mainland, .precision, .fitExtent, .fitSize, .fitWidth, .fitHeight, .stream, .invert). The composite adds:

• .getCompositionBorders() → SVG path d string, one rectangle per island inset.
• .drawCompositionBorders(context) → the same onto a Canvas 2D context.

geoColombiaCompositeWorld is the composite with a Natural Earth world inset tucked into the SW corner (for the diaspora vote). Colombia fits the band above the inset so the two never overlap. .invert routes across all sections, including the world box. It adds:

• .world() → the inset's geoNaturalEarth1 sub-projection — draw rest-of-world (consulado) features through it. Join them by ISO-3166 numeric id via the consulados map.
• .worldBox() → the inset's screen-space [[x0, y0], [x1, y1]], for layout or clipping.

The world inset has no rectangular composition border (the sphere outline is its own frame), so .getCompositionBorders() still returns only the two island boxes.

Data provenance

• Departamentos/municipios from DANE — Marco Geoestadístico Nacional (MGN); lon/lat (GCS MAGNA).
• San Andrés & Providencia coastlines from geoBoundaries COL ADM2 (CC BY 4.0), simplified and rewound to d3-geo winding.
• Colombia's Pacific islands (Malpelo, Gorgona) are uninhabited national parks with no separate municipio, so they are not inset.

Develop

npm install
npm test          # node --test
npm run example   # http-server on :8099

License

MIT © John Alexis Guerra Gómez