h3-js

H3 Geospatial Indexing — h3-js v4

H3 is Uber's hierarchical hexagonal geospatial indexing system. It tiles the sphere with hexagons at 16 resolutions (0-15), each ~7x finer than the last. The h3-js library provides JavaScript bindings for the H3 C library via emscripten.

npm install h3-js

import * as h3 from "h3-js"; // ESM
const h3 = require("h3-js"); // CJS

When to Use H3

• Aggregation — Bucket points into uniform cells with equidistant neighbors for heatmaps and density analysis.
• Joining disparate datasets — Index points, lines, and polygons into H3 cells to join datasets that share no common key except location.
• Flow modeling — Model movement between cells via directed edges. Uniform neighbor distances simplify weighting.
• Machine learning — Apply convolution and other CV techniques to the hex grid using k-rings and IJ coordinates.
• Multi-resolution analysis — Compact large cell sets into mixed-resolution representations, then uncompact for comparison at any resolution.

H3 vs Alternatives

System	Cell Shape	Hierarchy	Identifiers	Key Tradeoff
H3	Hexagon	Aperture 7, approximate containment	64-bit int	Equidistant neighbors; approximate subdivision
S2	Square	Aperture 4, exact containment	64-bit int	Exact subdivision; non-equidistant neighbors
Geohash	Rectangle	Exact containment	Variable-length string	Simple encoding; severe area distortion at poles
Hexbin	Hexagon	None	Projection-specific	Cheap to compute; no hierarchy, not portable
Admin boundaries	Irregular	None	Names/codes	Human-meaningful; incomparable sizes, change over time

Concepts

Understand these before using the API — they affect correctness.

Terminology

• Cell — A hexagon or pentagon in the H3 grid. Use "cell" in code; "hexagon"/"pentagon" only when the distinction matters.
• H3Index — 64-bit integer identifying any H3 object (cell, directed edge, or vertex). Represented as a 15-16 char hex string (e.g., "85283473fffffff").
• Directed edge — H3Index (mode 2) representing traversal from one cell to an adjacent cell.
• Vertex — H3Index representing a topological vertex of a cell.
• Base cell — One of 122 resolution-0 cells (110 hexagons, 12 pentagons). Every cell descends from one.
• Grid distance — Minimum number of hops across adjacent cells from one cell to another.

Pentagons

12 pentagons per resolution, centered on icosahedron vertices (all in ocean — land apps rarely hit them). Most functions handle pentagons transparently. Exceptions:

• gridRing can throw near pentagons — use gridDisk as the safe alternative.
• gridDistance, gridPathCells, and cellToLocalIj may fail across pentagonal distortion.
• Pentagon area is ~50% of hexagon area at the same resolution.

Hierarchical Containment Is Approximate

Child cell centers may fall outside their parent's boundary. Geographic containment is approximate; logical containment is exact. Use cellToParent/cellToChildren for logical hierarchy. For exact boundaries, combine H3 indexing with point-in-polygon checks.

compactCells / uncompactCells use logical containment and are exact.

Class II vs Class III

Resolutions alternate orientation by ~19.1 degrees. Even (0, 2, 4, ...) = Class II; odd (1, 3, 5, ...) = Class III. Matters for algorithms depending on grid alignment.

Coordinate Conventions

• Default coordinate order is lat/lng. Pass true as the formatAsGeoJson / isGeoJson parameter for lng/lat (GeoJSON) order.
• The coordinate reference system uses WGS84/EPSG:4326 with the authalic sphere radius.
• cellToBoundary may return more than 6 vertices for cells that cross icosahedron face boundaries.

Error Handling

Invalid inputs throw errors. Check .message for details.

try {
  h3.cellToChildrenSize("invalid", 9);
} catch (e) {
  console.error(e.message); // "Cell argument was not valid"
}

Common causes: invalid cell/edge/vertex, incompatible resolutions, cells too far apart for grid distance, pentagon distortion.

Resolution Guide

Each finer resolution has ~7x more cells. Total cells at resolution r: 2 + 120 * 7^r.

Res	Avg Hex Area	Avg Edge Length	Total Cells	Typical Use Case
0	4,357,449 km2	1,281 km	122	Continental
3	12,393 km2	69 km	41,162	Country / state
5	253 km2	9.9 km	2,016,842	Metro area
7	5.16 km2	1.4 km	98,825,162	Neighborhood
9	0.105 km2	201 m	4.8 billion	City block
11	0.00215 km2	28.7 m	237 billion	Building
13	43.9 m2	4.1 m	11.6 trillion	Room
15	0.9 m2	0.58 m	569 trillion	Sub-meter

Common Patterns

Find all cells within a radius of a point

Convert a radius (km) to a k-ring step count via average edge length.

const origin = h3.latLngToCell(lat, lng, 8);
const radiusKm = 4;
const edgeKm = h3.getHexagonEdgeLengthAvg(8, h3.UNITS.km);
const k = Math.floor(radiusKm / (edgeKm * 2));
const nearby = h3.gridDisk(origin, k);

Aggregate points into hex bins (heatmap)

Count points per cell for density visualization or analysis.

function aggregatePoints(points, res) {
  const counts = {};
  for (const { lat, lng } of points) {
    const cell = h3.latLngToCell(lat, lng, res);
    counts[cell] = (counts[cell] || 0) + 1;
  }
  return counts;
}

Weight points with distance falloff

Spread each point's influence across surrounding cells with linear decay by grid distance.

function weightWithFalloff(points, res, kRadius) {
  const weights = {};
  const step = 1 / (kRadius + 1);
  for (const { lat, lng } of points) {
    const origin = h3.latLngToCell(lat, lng, res);
    const rings = h3.gridDiskDistances(origin, kRadius);
    rings.forEach((ring, dist) => {
      for (const cell of ring) {
        weights[cell] = (weights[cell] || 0) + 1 - dist * step;
      }
    });
  }
  return weights;
}

Compact and uncompact cell sets

Reduce storage for large cell sets. All input cells must share the same resolution.

const cells = h3.polygonToCells(polygon, 9);
const compact = h3.compactCells(cells); // mixed-resolution, fewer cells
const restored = h3.uncompactCells(compact, 9); // back to uniform res 9

GeoJSON Interop

Coordinate Order

h3-js defaults to lat/lng ([37.77, -122.41]). GeoJSON requires lng/lat ([-122.41, 37.77]). Pass true for the isGeoJson/formatAsGeoJson parameter to switch. Most common integration bug: forgetting this.

Convert a single cell to a GeoJSON Feature

cellToBoundary returns coordinate arrays, not GeoJSON objects. Wrap manually.

function cellToFeature(cell, properties = {}) {
  const boundary = h3.cellToBoundary(cell, true); // true = GeoJSON [lng, lat] order
  return {
    type: "Feature",
    properties: { h3index: cell, ...properties },
    geometry: {
      type: "Polygon",
      coordinates: [[...boundary, boundary[0]]], // close the ring
    },
  };
}

Convert a set of cells to a GeoJSON FeatureCollection

One polygon feature per cell — useful for choropleth styling.

function cellsToFeatureCollection(cells, getProperties = () => ({})) {
  return {
    type: "FeatureCollection",
    features: cells.map((cell) => cellToFeature(cell, getProperties(cell))),
  };
}

Convert a set of cells to a merged GeoJSON outline

cellsToMultiPolygon merges adjacent cells into polygon outlines. All cells must share the same resolution with no duplicates — undefined behavior otherwise.

function cellsToOutlineFeature(cells) {
  const coordinates = h3.cellsToMultiPolygon(cells, true); // true = GeoJSON order
  return {
    type: "Feature",
    properties: {},
    geometry: { type: "MultiPolygon", coordinates },
  };
}

Convert a GeoJSON polygon to H3 cells

Pass isGeoJson = true so h3-js reads coordinates in lng/lat order.

function featureToCells(feature, res) {
  const coords = feature.geometry.coordinates;
  // coords[0] = outer ring, coords[1..n] = holes
  return h3.polygonToCells(coords, res, true);
}

Control containment mode when filling polygons

polygonToCells uses center containment by default — includes a cell only if its center is inside the polygon. Use polygonToCellsExperimental for other modes.

// Include cells that overlap the polygon boundary at all (fuller coverage)
h3.polygonToCellsExperimental(
  coords,
  res,
  h3.POLYGON_TO_CELLS_FLAGS.containment_overlapping,
  true,
);

// Include only cells fully contained within the polygon (stricter)
h3.polygonToCellsExperimental(
  coords,
  res,
  h3.POLYGON_TO_CELLS_FLAGS.containment_full,
  true,
);

geojson2h3 companion library

geojson2h3 provides higher-level conversion helpers:

npm install geojson2h3

import geojson2h3 from "geojson2h3";

// GeoJSON Feature → cell set
const cells = geojson2h3.featureToH3Set(geojsonFeature, res);

// Cell set → GeoJSON FeatureCollection (one Feature per cell)
const fc = geojson2h3.h3SetToFeatureCollection(cells, (cell) => ({
  value: data[cell],
}));

// Cell set → single merged GeoJSON Feature (outline)
const outline = geojson2h3.h3SetToFeature(cells);

API Reference

Indexing

h3.latLngToCell(lat, lng, resolution)    // → "85283473fffffff"
h3.cellToLatLng(cell)                     // → [lat, lng] (center point)
h3.cellToBoundary(cell, formatAsGeoJson?) // → [[lat, lng], ...] (vertices)

Inspection

h3.getResolution(cell); // → number (0-15)
h3.isValidCell(cell); // → boolean
h3.isPentagon(cell); // → boolean
h3.isResClassIII(cell); // → boolean
h3.getBaseCellNumber(cell); // → number (0-121)
h3.getIcosahedronFaces(cell); // → [faceNum, ...]

Hierarchy

h3.cellToParent(cell, parentRes); // → cell
h3.cellToChildren(cell, childRes); // → [cell, ...]
h3.cellToCenterChild(cell, childRes); // → cell
h3.compactCells(cells); // → mixed-resolution compact set
h3.uncompactCells(cells, res); // → uniform-resolution expanded set
h3.cellToChildPos(child, parentRes); // → position index
h3.childPosToCell(childPos, parent, childRes); // → cell

Traversal

h3.gridDisk(origin, k); // filled disk within k steps (safe near pentagons)
h3.gridDiskDistances(origin, k); // disk grouped by distance → [[ring0], [ring1], ...]
h3.gridRing(origin, k); // hollow ring at exactly k steps (may throw near pentagons)
h3.gridDistance(a, b); // grid distance (same resolution; may fail across pentagons)
h3.gridPathCells(start, end); // path of cells (inclusive; may fail across pentagons)
h3.cellToLocalIj(origin, cell); // → {i, j} (experimental; local to origin)
h3.localIjToCell(origin, { i, j }); // → cell (experimental)

Regions

// polygon = array of coordinate rings; first is outer boundary, rest are holes
h3.polygonToCells(polygon, res, isGeoJson?)
h3.cellsToMultiPolygon(cells, formatAsGeoJson?)  // all cells same res, no duplicates
h3.polygonToCellsExperimental(polygon, res, flags, isGeoJson?)
// flags: containment_center (default), containment_full, containment_overlapping, containment_overlapping_bbox

Directed Edges

h3.areNeighborCells(a, b); // → boolean
h3.cellsToDirectedEdge(origin, dest); // → edge index
h3.getDirectedEdgeOrigin(edge); // → cell
h3.getDirectedEdgeDestination(edge); // → cell
h3.directedEdgeToCells(edge); // → [origin, dest]
h3.originToDirectedEdges(cell); // → [edge, ...] (all 6 or 5 edges)
h3.directedEdgeToBoundary(edge); // → [[lat, lng], ...]

Vertexes

h3.cellToVertex(cell, vertexNum); // → vertex index (0-5 hex, 0-4 pentagon)
h3.cellToVertexes(cell); // → [vertex, ...]
h3.vertexToLatLng(vertex); // → [lat, lng]
h3.isValidVertex(vertex); // → boolean

Metrics & Utilities

h3.getHexagonAreaAvg(res, h3.UNITS.km2); // average hex area at resolution
h3.getHexagonEdgeLengthAvg(res, h3.UNITS.km); // average edge length at resolution
h3.cellArea(cell, h3.UNITS.km2); // exact area of a specific cell
h3.edgeLength(edge, h3.UNITS.km); // exact length of a specific edge
h3.getNumCells(res); // total cell count at resolution
h3.greatCircleDistance(point1, point2, h3.UNITS.km); // haversine distance ([lat,lng] points)
h3.getRes0Cells(); // all 122 base cells
h3.getPentagons(res); // 12 pentagons at resolution
h3.degsToRads(degrees);
h3.radsToDegs(radians);

Units: h3.UNITS.km2, h3.UNITS.m2, h3.UNITS.rads2, h3.UNITS.km, h3.UNITS.m, h3.UNITS.rads

v3 to v4 Migration

Function names changed in v4. The grid itself is unchanged — indexes from v3 are valid in v4.

v3	v4
geoToH3	latLngToCell
h3ToGeo	cellToLatLng
h3ToGeoBoundary	cellToBoundary
kRing	gridDisk
hexRing	gridRing
h3Distance	gridDistance
h3ToParent	cellToParent
h3ToChildren	cellToChildren
polyfill	polygonToCells
h3SetToMultiPolygon	cellsToMultiPolygon
compact	compactCells
uncompact	uncompactCells
h3IndexesAreNeighbors	areNeighborCells

See reference.md for the complete function name mapping.

Full Documentation

Complete API reference, algorithm internals, community libraries, and 40+ Observable notebooks in reference.md.