H3 geospatial

H3 Geospatial

Use this skill to work with Uber H3 in JavaScript/TypeScript, especially the h3-js package and the H3 4.x API documented at h3geo.org.

Workflow

1. Confirm the installed or target version when exact API behavior matters. As of 2026-07-21, h3-js latest is 4.5.0 and binds H3 core 4.5.0; re-check npm view h3-js version or the official README for version-sensitive work.
2. Choose the operation family before coding: indexing, inspection, hierarchy, traversal, regions, directed edges, vertices, metrics, or migration.
3. Normalize coordinate order up front. Default h3-js coordinate pairs are [lat, lng]; GeoJSON coordinate pairs are [lng, lat].
4. Validate H3 indexes and resolutions before expensive calls. Resolutions are integers 0 through 15.
5. Estimate output size before cellToChildren, gridDisk, polygonToCells, or uncompactCells; high resolutions can allocate huge arrays.
6. Add focused tests using small known cells and at least one coordinate-order assertion.

Source Order

• Prefer local project code and installed package types when editing an existing repo.
• Use the official uber/h3-js README and package types for JavaScript binding details.
• Use h3geo.org 4.x docs for H3 concepts, cross-language behavior, resolution stats, and error-code semantics.
• If docs conflict, trust the installed h3-js version for JavaScript names and signatures.

References

Load only the file needed for the current task:

• references/api-map.md: API groups, import patterns, v4 names, v3 migration names, units, flags, and errors.
• references/coordinates-geojson.md: coordinate order, GeoJSON conversion, polygon inputs, boundaries, and map-rendering shapes.
• references/resolution-and-scale.md: resolution selection, scale table, output-size risks, and performance guidance.
• references/implementation-patterns.md: concrete JavaScript/TypeScript patterns for bucketing, aggregation, polygon coverage, map output, traversal, and tests.

Default Rules

• Import from h3-js, not from the unrelated h3 HTTP framework package.
• Prefer named ESM imports in modern code:

import { latLngToCell, cellToBoundary, polygonToCells } from "h3-js";

• Store H3 indexes as strings. Do not coerce them to JavaScript numbers; they are 64-bit hexadecimal identifiers.
• Use v4 function names in new code: latLngToCell, cellToLatLng, cellToBoundary, polygonToCells, gridDisk, gridDistance, cellToParent, cellToChildren, compactCells, uncompactCells.
• Do not use v3 names like geoToH3, h3ToGeo, h3ToGeoBoundary, polyfill, kRing, or h3Distance unless deliberately touching legacy code.
• Treat H3 hierarchy as exact logical indexing, not exact geometric containment. A child cell belongs to a parent index logically, but cell boundaries are not always geometrically contained by the parent boundary.
• Use polygonToCells for centroid-based polygon coverage. Use polygonToCellsExperimental with explicit POLYGON_TO_CELLS_FLAGS only when the containment mode is part of the requirement.
• Use compactCells to reduce storage or network payload for complete child sets; compactCells rejects invalid inputs such as duplicate cells.
• Catch h3-js errors around user-provided polygons, indexes, resolutions, and large expansions; H3 4.x generally throws instead of returning null-like failure values.

Verification

For code changes involving H3:

• Run a small point round trip: latLngToCell then cellToLatLng.
• For GeoJSON output, assert cellToBoundary(cell, true) returns [lng, lat] pairs and a closed ring.
• For polygon input, test both a default [lat, lng] polygon and a GeoJSON [lng, lat] polygon with isGeoJson: true when applicable.
• For traversal, include a pentagon-adjacent or error-path test when using gridRingUnsafe, local IJ functions, or long paths.
• For storage/query code, test duplicate handling and compaction/uncompaction at the intended resolution.