The Complete Production SOP: How to Deploy and Run Uber H3 Hierarchical Hexagonal Spatial Indexing in Autonomous AI Agents

---
name: "uber-h3-hexagonal-spatial-index"
description: "Partition geographic coordinates into multi-resolution hexagonal grid cells using Uber H3."
metadata:
  author: "Uber"
  version: "1.0.0"
  runtime_compatibility:
    - "codex"
    - "claude-code"
    - "cursor"
    - "windsurf"
triggers:
  - "lat lng to h3 index"
  - "polygon polyfill h3"
  - "h3 grid aggregation"
permissions:
  fs_read: true
  fs_write: "workspace"
  shell_exec: false
  net_access: false
---

# Uber H3 Hierarchical Hexagonal Spatial Indexing

Implements spatial analytics using Uber H3: converting lat/lng to H3 index tokens, finding k-ring neighbors, compacting and uncompacting cell sets, polyfilling polygons, and running high-speed spatial aggregations.

## When to Invoke
Invoke this skill whenever you need to:
- lat lng to h3 index
- polygon polyfill h3
- h3 grid aggregation

## Execution SOP & Rules
1. Target H3 v4 API syntax: use h3.latlng_to_cell(lat, lng, res) instead of deprecated v3 h3.geo_to_h3.
2. Neighbor searches must use h3.grid_disk(cell, k) or h3.grid_ring_unsafe(cell, k).
3. Polygon ingestion must use h3.polygon_to_cells(geo_polygon, res) with GeoJSON coordinate order [lng, lat].
4. Always compact collections using h3.compact_cells() when persisting boundaries to Parquet/JSON.

## Verification Checklist
- Verify H3 cell strings are valid hex using h3.is_valid_cell().
- Assert coordinate inputs fall within [-90.0, 90.0] latitude and [-180.0, 180.0] longitude.
- Confirm resolution is an integer between 0 and 15 inclusive.

import h3
import sys

test_lat, test_lng, res = 37.7749, -122.4194, 9
try:
    # Verify H3 v4 API signature
    cell = h3.latlng_to_cell(test_lat, test_lng, res)
    assert h3.is_valid_cell(cell), f"Invalid H3 index: {cell}"
    disk = h3.grid_disk(cell, 1)
    assert len(disk) == 7, f"Expected 7 cells in k=1 ring, got {len(disk)}"
    print(f"[SUCCESS] H3 runtime operational. Version: {h3.__version__}, Sample Cell: {cell}")
except AttributeError as e:
    sys.exit(f"[FAIL] H3 v3/v4 API mismatch detected: {e}")
except Exception as e:
    sys.exit(f"[FAIL] Unexpected error during verification: {e}")

import h3
import pandas as pd
from pathlib import Path

def aggregate_telemetry_by_h3(input_path: Path, output_path: Path, resolution: int = 8) -> None:
    """Converts coordinate records into H3 cells and performs spatial density aggregation."""
    df = pd.read_csv(input_path)
    
    # Validate coordinates
    valid_coords = df['latitude'].between(-90, 90) & df['longitude'].between(-180, 180)
    df = df[valid_coords].copy()
    
    # Map coordinates to H3 index
    df['h3_cell'] = [h3.latlng_to_cell(lat, lng, resolution) for lat, lng in zip(df['latitude'], df['longitude'])]
    
    # High-speed categorical aggregation
    aggregated = df.groupby('h3_cell').agg(
        ping_count=('h3_cell', 'count'),
        avg_speed=('speed', 'mean') if 'speed' in df.columns else ('latitude', 'count')
    ).reset_index()
    
    # Compute boundary polygon for downstream visualization
    aggregated['hex_boundary_geojson'] = aggregated['h3_cell'].apply(
        lambda c: h3.cell_to_boundary(c, geo_json=True)
    )
    
    output_path.parent.mkdir(parents=True, exist_ok=True)
    aggregated.to_parquet(output_path, index=False)
    print(f"Processed {len(df)} pings into {len(aggregated)} distinct H3 cells at resolution {resolution}.")

import pytest
import h3
import pandas as pd
from pathlib import Path

def test_h3_output_integrity(tmp_path):
    from h3_aggregator import aggregate_telemetry_by_h3
    
    # Generate test fixture
    raw_csv = tmp_path / "raw.csv"
    out_parquet = tmp_path / "out.parquet"
    pd.DataFrame({
        'latitude': [37.7749, 37.7750, 40.7128],
        'longitude': [-122.4194, -122.4195, -74.0060],
        'speed': [15.2, 14.8, 30.1]
    }).to_csv(raw_csv, index=False)
    
    aggregate_telemetry_by_h3(raw_csv, out_parquet, resolution=8)
    
    res_df = pd.read_parquet(out_parquet)
    assert not res_df.empty, "Result dataframe should not be empty"
    assert 'h3_cell' in res_df.columns, "H3 cell column missing"
    
    # Validate individual H3 cells
    for cell in res_df['h3_cell']:
        assert h3.is_valid_cell(cell), f"Invalid H3 cell detected: {cell}"
        assert h3.get_resolution(cell) == 8, f"Resolution mismatch: expected 8, got {h3.get_resolution(cell)}"