H3 Performance & Integration

Trade-Offs and Limitations

H3 isn’t perfect. Understanding its limitations helps you use it effectively and avoid pitfalls.

1. Pentagons

Due to the icosahedron projection, there are 12 pentagons (5-sided cells instead of 6-sided) at each resolution, located at the icosahedron vertices.

Impact:

• Edge cases in neighbor traversal algorithms (pentagons have 5 neighbors, not 6)
• Slightly distorted areas near pentagons
• Some H3 operations return errors or special handling for pentagons
• Parent-child relationships differ (pentagons don’t split into 7 children)

1
# Check if a cell is a pentagon
2
is_pent = h3.h3_is_pentagon('8009fffffffffff')  # Resolution 0 example
3
print(is_pent)  # True
4

5
# Pentagons have only 5 neighbors
6
neighbors = h3.k_ring('8009fffffffffff', 1)
7
print(len(neighbors))  # 6 (cell + 5 neighbors, not cell + 6)

Mitigation:

• H3 library functions handle pentagons automatically
• If writing custom algorithms, use h3.h3_is_pentagon() to check and branch
• For most applications, pentagons are rare enough (~0.001% of cells) to ignore

2. Discretization Error

Hexagons are approximations of continuous space. Two points in the same hexagon are treated as identical.

Example: At resolution 9 (~0.1km² cells, ~175m edge), two points 100m apart might map to:

• Same cell → Treated as identical (0m apart in H3 logic)
• Adjacent cells → 1 hop apart (depending on hexagon boundary placement)

Real-world impact:

1
# Two restaurants 100m apart
2
restaurant_a_h3 = h3.geo_to_h3(37.7749, -122.4194, 9)
3
restaurant_b_h3 = h3.geo_to_h3(37.7758, -122.4194, 9)  # ~100m north
4

5
# Might be same cell or different cells!
6
if restaurant_a_h3 == restaurant_b_h3:
7
    print("H3 treats them as identical location")
8
else:
9
    print("H3 treats them as separate locations")

Mitigation:

• Choose resolution appropriate for your accuracy needs
• Use hybrid approach: H3 for filtering, exact distance for final results
• For very precise applications (< 10m), use resolution 12+
• Store raw lat/lng alongside H3 index for exact fallback

3. Storage Overhead

Every point needs an H3 index stored alongside its original coordinates (if you need exact positions).

Example:

• Raw coordinates: 16 bytes (2 × 8-byte doubles)
• H3 index: 8 bytes (64-bit integer)
• Total: 24 bytes per location

For 1 billion locations:

• Coordinates alone: 16 GB
• With H3 indexes: 24 GB
• Overhead: 8 GB (50% increase)

Mitigation:

• If you only need H3 for analysis, can drop raw coordinates for some use cases
• Multiple resolution indexes multiply storage (8 GB per resolution)
• Index compression: H3 indexes compress well (many share prefixes)

4. Not Ideal for Linear Features

H3 is optimized for area-based analysis (density, coverage, aggregation). It’s less efficient for:

Road networks:

• Roads are linear (1D), hexagons are areal (2D)
• A straight road crosses many hexagon boundaries
• Better to use specialized routing graphs (OpenStreetMap, GraphHopper)

Pipelines or railroads:

• Long linear features don’t align with hexagonal grid
• Use S2 (square grid better for edges) or specialized geometry

Navigation and routing:

• H3 doesn’t understand road connectivity or turn restrictions
• Use dedicated routing algorithms (Dijkstra, A* on road graphs)

5. Learning Curve

Understanding hierarchical hexagonal indexing requires upfront investment:

Your team needs to learn:

• Resolution selection (which resolution for which use case?)
• Hierarchy navigation (parent/child operations)
• Neighbor traversal logic (k-ring vs hex-ring vs grid-distance)
• When to aggregate vs. drill down
• Pentagon edge cases

Documentation and tooling:

• H3 documentation is excellent, but assumes geospatial knowledge
• Debugging can be tricky (why did this cell get included in polyfill?)
• Visualization tools help (Kepler.gl, H3-React components)

Mitigation:

• Start with simple use cases (proximity search)
• Build shared libraries wrapping common patterns
• Invest in visualization tools for debugging

Integration and Performance

Database Integration

PostgreSQL with h3-pg Extension

1
-- 1. Install extension
2
CREATE EXTENSION h3;
3

4
-- 2. Add H3 index column
5
ALTER TABLE locations ADD COLUMN h3_index h3index;
6

7
-- 3. Populate H3 indexes (one-time or on insert trigger)
8
UPDATE locations
9
SET h3_index = h3_lat_lng_to_cell(lat, lng, 9);
10

11
-- 4. Create B-tree index on H3 column
12
CREATE INDEX idx_locations_h3 ON locations (h3_index);
13

14
-- 5. Query nearby locations
15
-- Find all locations in target cell + 2-hop neighbors
16
SELECT * FROM locations
17
WHERE h3_index = ANY(
18
  SELECT h3_grid_disk('8928308280bffff', 2)
19
);
20
-- Returns ~19 hexagons worth of results
21

22
-- 6. Aggregate by hexagon
23
SELECT
24
  h3_index,
25
  COUNT(*) as location_count,
26
  AVG(rating) as avg_rating
27
FROM restaurants
28
WHERE h3_index = ANY(
29
  SELECT h3_grid_disk(h3_lat_lng_to_cell(37.7749, -122.4194, 9), 5)
30
)
31
GROUP BY h3_index;

Performance:

• Index lookup: ~1-10ms for 1M rows
• Aggregate query: ~10-50ms depending on cell count
• Scales linearly with number of hexagons queried

Redis with H3

1
import redis
2
import h3
3

4
r = redis.Redis()
5

6
# Store driver locations by H3 cell
7
def index_driver(driver_id, lat, lng):
8
    h3_index = h3.geo_to_h3(lat, lng, 9)
9

10
    # Add to set for this cell
11
    r.sadd(f'drivers:cell:{h3_index}', driver_id)
12

13
    # Store driver details
14
    r.hset(f'driver:{driver_id}', mapping={
15
        'lat': lat,
16
        'lng': lng,
17
        'h3_index': h3_index
18
    })
19

20
# Find nearby drivers (fast!)
21
def find_nearby_drivers(rider_lat, rider_lng, k_ring=2):
22
    rider_h3 = h3.geo_to_h3(rider_lat, rider_lng, 9)
23
    nearby_cells = h3.k_ring(rider_h3, k_ring)
24

25
    # Collect drivers from all nearby cells
26
    drivers = set()
27
    for cell in nearby_cells:
28
        cell_drivers = r.smembers(f'drivers:cell:{cell}')
29
        drivers.update(cell_drivers)
30

31
    return list(drivers)
32

33
# Update driver location (must remove from old cell, add to new)
34
def update_driver_location(driver_id, new_lat, new_lng):
35
    # Get old cell
36
    old_h3 = r.hget(f'driver:{driver_id}', 'h3_index')
37

38
    # Calculate new cell
39
    new_h3 = h3.geo_to_h3(new_lat, new_lng, 9)
40

41
    # Only update if cell changed
42
    if old_h3 != new_h3:
43
        r.srem(f'drivers:cell:{old_h3}', driver_id)
44
        r.sadd(f'drivers:cell:{new_h3}', driver_id)
45

46
    # Update driver details
47
    r.hset(f'driver:{driver_id}', mapping={
48
        'lat': new_lat,
49
        'lng': new_lng,
50
        'h3_index': new_h3
51
    })

Performance:

• Driver indexing: < 1ms
• Nearby driver search: < 5ms for k_ring=2 (19 cells)
• Scales to millions of drivers with Redis clustering

Performance Characteristics

Coordinate → H3 Index:

• ~100-500 nanoseconds (pure computation, no I/O)
• CPU-bound, highly optimized C implementation
• No allocations, suitable for hot paths

k-Ring (k=2):

• ~1-5 microseconds (returns 19 cells)
• Precomputed lookup tables for small k
• Scales with 3k(k+1) formula

Polyfill (medium polygon):

• ~10-100 microseconds (depends on resolution and polygon complexity)
• Polygon with 100 vertices at resolution 9: ~50μs
• Scales with polygon area and resolution

Database query with H3 index:

• ~1-10 milliseconds (standard B-tree index lookup)
• Depends on number of cells queried (k-ring size)
• ~1ms per 10-20 cells on modern hardware

Best Practices

1. Choose the Right Resolution

Too Coarse (resolution 5-7):

• ❌ Lumps together unrelated areas
• ❌ Poor accuracy for small-scale features
• ❌ User experience: “Why is this restaurant 2km away showing as ‘nearby’?”

Too Fine (resolution 12-15):

• ❌ Too many cells (storage bloat)
• ❌ Excessive query complexity (k_ring returns hundreds of cells)
• ❌ Diminishing returns on accuracy

Sweet Spot for most applications:

Rule of thumb: Choose resolution where cell edge is ~1/3 of your typical query radius. For a 1km proximity search, use resolution 9 (175m edge).

2. Precompute and Store H3 Indexes

Don’t convert coordinates on every query:

1
-- ❌ BAD: Converts on every query (slow!)
2
SELECT * FROM locations
3
WHERE h3_lat_lng_to_cell(lat, lng, 9) IN (nearby_cells);

Do precompute and index:

1
-- ✅ GOOD: Uses indexed column (fast!)
2
SELECT * FROM locations
3
WHERE h3_index IN (nearby_cells);

Implementation:

• Add H3 column to table schema
• Populate on insert/update (trigger or application logic)
• Create B-tree index on H3 column
• Refresh/rebuild periodically if using dynamic resolutions

3. Use Appropriate k-Ring Values

k=1: Immediate neighbors

• Returns: 7 cells (center + 6 neighbors)
• Coverage: ~1.2km² at resolution 9
• Use for: Tight proximity (within ~500m)

k=2: 2-hop neighbors

• Returns: 19 cells (center + 2 rings)
• Coverage: ~3.4km² at resolution 9
• Use for: Medium proximity (within ~1km)

k=3: 3-hop neighbors

• Returns: 37 cells (center + 3 rings)
• Coverage: ~6.5km² at resolution 9
• Use for: Wide proximity (within ~1.5km)

Warning: k grows quadratically!

• k=5: 91 cells
• k=10: 331 cells
• k=20: 1,261 cells

For large radii, consider using lower resolution instead of large k values.

4. Combine with Traditional Indexes

Use H3 as a fast filter, then refine with exact calculations:

1
# Pattern: H3 filter + exact refinement
2

3
# Step 1: Fast H3 filter (reduces 1M points to ~100 candidates)
4
user_h3 = h3.geo_to_h3(user_lat, user_lng, 9)
5
candidate_cells = h3.k_ring(user_h3, 2)
6

7
candidates = db.query("""
8
    SELECT * FROM restaurants
9
    WHERE h3_index IN (%s)
10
""", candidate_cells)
11
# Returns ~100 restaurants
12

13
# Step 2: Exact distance refinement (only 100 calculations, not 1M!)
14
results = []
15
for restaurant in candidates:
16
    distance = haversine_distance(
17
        user_lat, user_lng,
18
        restaurant.lat, restaurant.lng
19
    )
20
    if distance < 2000:  # 2km exact radius
21
        results.append({
22
            'restaurant': restaurant,
23
            'distance_m': distance
24
        })
25

26
results.sort(key=lambda x: x['distance_m'])
27
return results[:10]  # Top 10 closest

This hybrid approach gets 99% of H3’s speed with 100% geographic accuracy.

Conclusion

H3 transforms geospatial problems from complex geometric calculations into simple index lookups. By discretizing the world into hierarchical hexagons, it makes location-based queries orders of magnitude faster while enabling new types of analysis.

Key Takeaways:

• Understand trade-offs: Pentagons, discretization error, storage overhead
• Choose resolution wisely: Balance accuracy vs. performance
• Integrate properly: Precomputed indexes, hybrid filtering
• Use best practices: Appropriate k-ring values, database indexing

When to use H3:

• ✅ Area-based analysis (density, coverage, heatmaps)
• ✅ Aggregation and drill-down at multiple resolutions
• ✅ Fast proximity queries at scale
• ✅ Privacy-preserving location data

When NOT to use H3:

• ❌ Precise distance measurements (use exact calculations)
• ❌ Linear features like roads (use specialized routing systems)
• ❌ Navigation and routing (use routing graphs)
• ❌ Sub-meter precision requirements

Understanding H3 deepens your knowledge of spatial indexing, hierarchical data structures, and performance trade-offs in distributed systems. H3 is open-source (h3geo.org) with libraries for Python, JavaScript, Java, Go, and more.

Start experimenting to see how hexagonal thinking can transform your geospatial applications!