H3 Operations

Core H3 Operations

H3 provides a rich API for geospatial operations. Once you understand these core functions, you can build sophisticated location-based features with just a few lines of code.

All examples use the JavaScript API, but the concepts apply to Python, Java, Go, and other language bindings.

1. Conversion Functions

These functions translate between geographic coordinates and H3 indexes.

geoToH3: Coordinates → H3 Index

Convert latitude/longitude to an H3 cell index:

1
const h3 = require('h3-js');
2

3
// Uber HQ in San Francisco
4
const h3Index = h3.geoToH3(37.7749, -122.4194, 9);
5
console.log(h3Index);
6
// Output: '8928308280bffff'

Parameters:

• lat: Latitude (-90 to 90)
• lng: Longitude (-180 to 180)
• resolution: Resolution level (0-15)

Use cases:

• Index user locations for fast lookup
• Convert GPS coordinates from mobile devices
• Precompute indexes for static locations (stores, landmarks)

h3ToGeo: H3 Index → Center Coordinates

Get the center point of an H3 cell:

1
const [lat, lng] = h3.h3ToGeo('8928308280bffff');
2
console.log(`Center: ${lat}, ${lng}`);
3
// Output: Center: 37.7749, -122.4194

Use cases:

• Display marker on a map for an H3 cell
• Calculate approximate distances between cells
• Render cell centers in visualizations

h3ToGeoBoundary: H3 Index → Hexagon Vertices

Get the 6 vertices of the hexagon boundary:

1
const boundary = h3.h3ToGeoBoundary('8928308280bffff');
2
console.log(boundary);
3
// Output: Array of 6 [lat, lng] pairs
4
// [[37.7751, -122.4196], [37.7753, -122.4193], ...]

Use cases:

• Draw hexagon polygons on maps
• Calculate actual cell area
• Visualize H3 grid overlays

2. Hierarchy Functions

Navigate the multi-resolution hierarchy.

h3ToParent: Zoom Out

Get the parent cell at a coarser resolution:

1
// Street block (resolution 9)
2
const streetBlock = '8928308280bffff';
3

4
// Get neighborhood (resolution 7)
5
const neighborhood = h3.h3ToParent(streetBlock, 7);
6
console.log(neighborhood);
7
// Output: '872830828ffffff'

Use cases:

• Aggregate fine-grained data to coarser levels
• Build drill-down interfaces
• Create hierarchical indexes for multi-scale queries

h3ToChildren: Zoom In

Get all child cells at a finer resolution:

1
// Neighborhood (resolution 7)
2
const neighborhood = '872830828ffffff';
3

4
// Get all street blocks (resolution 9)
5
const streetBlocks = h3.h3ToChildren(neighborhood, 9);
6
console.log(streetBlocks.length);
7
// Output: 49 (7 x 7, two levels down)

Use cases:

• Progressive disclosure (show overview, load details on demand)
• Split coarse cells for finer analysis
• Generate comprehensive coverage of a region

3. Neighbor Functions

Find adjacent and nearby cells.

kRing: Get Filled Disk of Neighbors

Get all cells within k steps (includes the origin cell):

1
const center = '8928308280bffff';
2

3
// Get 1-ring (cell + 6 immediate neighbors = 7 cells)
4
const ring1 = h3.kRing(center, 1);
5
console.log(ring1.length); // 7
6

7
// Get 2-ring (cell + up to 18 neighbors = 19 cells)
8
const ring2 = h3.kRing(center, 2);
9
console.log(ring2.length); // 19
10

11
// Get 3-ring (37 cells)
12
const ring3 = h3.kRing(center, 3);
13
console.log(ring3.length); // 37

Formula: k-ring returns 1 + 3k(k+1) cells for perfect hexagons.

Use cases:

• Find nearby drivers/restaurants within N hops
• Smooth heatmap boundaries
• Create buffer zones around points of interest

hexRing: Get Hollow Ring

Get only cells at exactly k steps away (hollow ring):

1
const center = '8928308280bffff';
2

3
// Only cells at distance 2 (not 0 or 1)
4
const ring2 = h3.hexRing(center, 2);
5
console.log(ring2.length); // 12

Formula: Hollow ring at distance k has 6k cells (for k > 0).

Use cases:

• Expand search radius incrementally
• Visualize distance contours
• Implement progressive search (search ring 1, then ring 2 if not found, etc.)

gridDistance: Manhattan Distance Between Cells

Get the minimum number of hops between two cells:

1
const cell1 = '8928308280bffff';
2
const cell2 = '8928308281bffff';
3

4
const distance = h3.gridDistance(cell1, cell2);
5
console.log(distance); // 3 (cells are 3 hops apart)

Use cases:

• Filter by grid proximity (faster than haversine distance)
• Sort results by grid distance
• Validate that cells are actually neighbors

4. Region Functions

Work with polygons and regions.

polyfill: Fill Polygon with Hexagons

Get all H3 cells that cover a polygon:

1
// GeoJSON polygon (e.g., downtown San Francisco)
2
const polygon = {
3
  type: 'Polygon',
4
  coordinates: [[
5
    [-122.4194, 37.7749],
6
    [-122.4100, 37.7749],
7
    [-122.4100, 37.7850],
8
    [-122.4194, 37.7850],
9
    [-122.4194, 37.7749]
10
  ]]
11
};
12

13
// Fill with resolution 9 hexagons
14
const hexagons = h3.polyfill(polygon, 9);
15
console.log(hexagons.length); // ~50-100 hexagons

Use cases:

• Define delivery zones for restaurants
• Create geofenced regions
• Index arbitrary shapes (parks, neighborhoods, city boundaries)

h3SetToMultiPolygon: Hexagons → Polygon

Convert a set of H3 cells back into GeoJSON polygons:

1
const hexagons = [
2
  '8928308280bffff',
3
  '8928308280cffff',
4
  '8928308281bffff'
5
];
6

7
const polygon = h3.h3SetToMultiPolygon(hexagons);
8
console.log(polygon);
9
// Output: GeoJSON MultiPolygon representing the combined shape

Use cases:

• Visualize aggregated regions
• Export coverage areas as standard GeoJSON
• Reconstruct service areas from indexed cells

5. Edge Functions

Analyze movement and connectivity between cells.

getH3UnidirectionalEdge: Track Movement

Get the directed edge between two adjacent cells:

1
const origin = '8928308280bffff';
2
const destination = '8928308280cffff';
3

4
// Get the edge representing this movement
5
const edge = h3.getH3UnidirectionalEdge(origin, destination);
6
console.log(edge);
7
// Output: '16928308280bffff' (edge index)

Why edges matter:

• Each hexagon has 6 edges (one per side)
• Edges are directed: origin→destination ≠ destination→origin
• Edges have their own indexes, separate from cells

Use cases:

• Analyze traffic flow patterns
• Track driver routes (sequence of edges)
• Build road network representations
• Measure congestion on specific hexagon boundaries

getH3UnidirectionalEdgeBoundary: Edge Geometry

Get the geographic coordinates of an edge:

1
const edge = '16928308280bffff';
2
const boundary = h3.getH3UnidirectionalEdgeBoundary(edge);
3
console.log(boundary);
4
// Output: Array of 2 [lat, lng] pairs (the shared edge vertices)

Use cases:

• Draw movement arrows on maps
• Visualize traffic flow
• Calculate edge lengths

Common Patterns and Combinations

Pattern 1: Proximity Search with Filtering

1
// Find nearby restaurants within 500m
2
const userLocation = h3.geoToH3(userLat, userLng, 9);
3
const nearbyHexagons = h3.kRing(userLocation, 2); // ~19 hexagons
4

5
// Fast index lookup
6
const candidates = restaurants.filter(r =>
7
  nearbyHexagons.includes(r.h3Index)
8
);
9

10
// Refine with exact distance
11
const nearby = candidates.filter(r =>
12
  haversineDistance(userLat, userLng, r.lat, r.lng) < 500
13
);

Result: Fast indexing narrows 10,000 restaurants to ~50 candidates, then exact filtering gives precise results.

Pattern 2: Hierarchical Heatmap

1
// High-detail heatmap for zoomed-in view
2
const detailData = getDataAtResolution(9);
3

4
// Aggregate to coarser resolution for zoomed-out view
5
const overviewData = {};
6
for (const [cell, value] of Object.entries(detailData)) {
7
  const parent = h3.h3ToParent(cell, 7);
8
  overviewData[parent] = (overviewData[parent] || 0) + value;
9
}
10

11
// Render appropriate resolution based on map zoom level
12
const dataToRender = (mapZoom > 12) ? detailData : overviewData;

Pattern 3: Coverage Analysis

1
// Define service area
2
const servicePolygon = restaurantDeliveryZone;
3
const serviceHexagons = new Set(h3.polyfill(servicePolygon, 9));
4

5
// Check if customer is in coverage
6
const customerHex = h3.geoToH3(customerLat, customerLng, 9);
7
const inCoverage = serviceHexagons.has(customerHex);
8

9
// Or check 1-ring for "near boundary" cases
10
const customerRing = h3.kRing(customerHex, 1);
11
const nearCoverage = customerRing.some(hex => serviceHexagons.has(hex));

Conclusion

H3’s API is designed for intuitive geospatial operations:

• Conversion functions translate between coordinates and indexes
• Hierarchy functions enable multi-scale analysis
• Neighbor functions find nearby cells efficiently
• Region functions work with arbitrary shapes
• Edge functions track movement and connectivity

Master these operations, and you can build sophisticated location-based features with minimal code.

Next, let’s see how these operations power real-world Use Cases at companies like Uber and DoorDash.