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

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.

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.

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.