H3 Spatial Indexing

Overview

The H3 Spatial Indexing service is a geospatial utility microservice providing hexagonal spatial indexing and polygon operations for the OR platform. Developed for an OR Alpha project, it serves as the spatial computation backend that enables grid-based spatial analysis, zone assignment, and multi-resolution aggregation for fire risk mapping and location intelligence.

The service converts between geographic coordinates, hexagonal grid cells, and polygon boundaries — enabling the Fire Spread Modelling service to work with real-world terrain data indexed at hexagonal resolution levels.

Architecture

The H3 Spatial Indexing service is built as a lightweight web service that integrates with the OR platform through standardized data interfaces. It provides HTTP endpoints for spatial operations and follows platform conventions for health monitoring and API documentation.

Platform Integration

The service integrates seamlessly with the OR platform's workflow orchestration system, allowing spatial operations to be composed into larger computational pipelines. It supports health monitoring for deployment management and provides interactive API documentation for developers and integrators.

Capabilities

Coordinate to Hexagon Conversion

Convert between geographic coordinates and hexagonal cell indices at any resolution level (0–15).

Geographic Coordinates to Hexagonal Cells

Converts a geographic coordinate to its enclosing hexagonal grid cell.

Endpoint	Input	Parameters	Output
POST /latlon_to_h3	latitude, longitude	resolution (0–15, default: 9)	h3_index, resolution, input coordinates
POST /latlon_to_h3_bulk	Array of coordinate pairs	resolution (0–15, default: 9)	Array of hexagon results (h3_index, lat, lon), total_converted

Hexagonal Cells to Geographic Coordinates

Converts a hexagonal cell index back to its hexagon centre-point coordinates.

Endpoint	Input	Parameters	Output
POST /h3_to_latlon	h3_index	validate_h3_index (default: true)	latitude, longitude, resolution
POST /h3_to_latlon_bulk	Array of hexagon indices	validate_h3_indices, skip_invalid	Array of coordinate results, total_converted

Hexagonal Hierarchy Navigation

Navigate between resolution levels in the hexagonal hierarchy. Each parent cell contains approximately 7 children at the next finer resolution.

Parent to Children (Zoom In)

Expands a parent hexagonal cell to all child cells at a higher (finer) resolution.

Endpoint	Input	Parameters	Output
POST /h3_parent_to_children	parent_h3_index, child_resolution	validate_h3_index, include_parent_info (area, coordinates)	child_h3_indices, total_children, resolution_difference, optional parent_info
POST /h3_parent_to_children_bulk	Array of parent indices, child_resolution	validate_h3_indices, skip_invalid, deduplicate_children	Per-parent results, all child indices (deduplicated), duplicates_removed

The bulk variant deduplicates overlapping children from adjacent parents — essential when expanding contiguous regions.

Child to Parent (Zoom Out)

Maps a child hexagonal cell to its parent at a lower (coarser) resolution. Each child has exactly one parent at any given resolution.

Endpoint	Input	Parameters	Output
POST /h3_child_to_parent	child_h3_index, parent_resolution	validate_h3_index, include_child_info	parent_h3_index, parent_latitude, parent_longitude, resolution_difference
POST /h3_child_to_parent_bulk	Array of child indices, parent_resolution	validate_h3_indices, skip_invalid	Per-child results, unique_parents (deduplicated), total_unique_parents

The bulk variant identifies unique parents — siblings that share the same parent are naturally deduplicated.

Polygon Operations

Polygon Intersection (Zone Assignment)

Determines which polygon from a GeoJSON FeatureCollection contains each point, using a three-tier matching strategy:

1. Exact match — point is geometrically inside a polygon
2. Buffer match — point is within a configurable buffer distance of a polygon boundary
3. Nearest match — finds the closest polygon within a maximum search distance

The service uses geospatial processing libraries with automatic geometry validation and repair, supporting standard geographic coordinate systems.

Endpoint	Input	Parameters
POST /polygon_intersect	GeoJSON FeatureCollection (polygons with id), array of PointWithId (id, lat, lon)	buffer_distance_meters (default: 5000), find_nearest_if_no_match (default: true), max_distance_for_nearest (default: 50000m)

Response per point: intersecting_polygon_id, polygon_properties, distance_to_polygon (0 if inside, metres if buffer/nearest), match_type (exact / buffer / nearest / none).

Polygon to Hexagonal Grid (Grid Coverage)

Converts polygon boundaries to hexagonal grid coverage. Supports Polygon, MultiPolygon, Feature, and FeatureCollection inputs.

For MultiPolygon and FeatureCollection inputs, each polygon is processed separately and the hexagonal cell sets are combined. Invalid geometries are automatically repaired using standard geospatial techniques.

Endpoint	Input	Parameters	Output
POST /polygon_to_h3	GeoJSON Polygon, MultiPolygon, Feature, or FeatureCollection	resolution (0–15, default: 5), combine_all_features (default: true)	h3_indices, total_hexagons, area_info (hexagon area, total area, geometry type), features_processed

Hexagonal Resolution Reference

Resolution	Hexagon Area	Typical Use
0–3	4,250–100,000 km²	Continental / country scale
4–6	7–1,000 km²	State / province scale
7–9	0.1–5 km²	City / neighbourhood scale
10–12	15 m²–45,000 m²	Street / building scale
13–15	0.9–9 m²	Precise / indoor scale

The Fire Spread Modelling service uses resolution 4 (approximately 25 km² per hexagon) for national-scale terrain indexing in the terrain reference database table.

API Endpoints

Endpoint	Method	Category	Purpose
/live	GET	Health	Liveness probe
/ready	GET	Health	Readiness probe
/latlon_to_h3	POST	Geocoding	Single coordinate → H3 index
/latlon_to_h3_bulk	POST	Geocoding	Batch coordinates → H3 indices
/h3_to_latlon	POST	Geocoding	Single H3 index → centre lat/lon
/h3_to_latlon_bulk	POST	Geocoding	Batch H3 indices → coordinates
/h3_parent_to_children	POST	H3 Hierarchy	Single parent → all child cells
/h3_parent_to_children_bulk	POST	H3 Hierarchy	Batch parents → children with dedup
/h3_child_to_parent	POST	H3 Hierarchy	Single child → parent cell
/h3_child_to_parent_bulk	POST	H3 Hierarchy	Batch children → parents with unique parent identification
/polygon_intersect	POST	Geospatial	Point-in-polygon zone assignment
/polygon_to_h3	POST	Geospatial	Polygon boundary → H3 grid coverage

Deployment

The H3 Spatial Indexing service is deployed as a containerized microservice within the OR platform infrastructure. It follows standard cloud deployment practices with automated build and test pipelines, ensuring reliable delivery of spatial computation capabilities to the platform.