core-indexing

Core H3 indexing

Use this route when a user needs to turn a latitude/longitude into an H3 cell, inspect a cell or index, move through the hierarchy or neighboring grid, create edges or vertices, use local IJ coordinates, measure spherical quantities, or validate inputs. The public default is the h3 string API: scalar indexes are canonical lowercase hexadecimal strings and collections are ordinary Python lists unless a function documents an unordered result.

• Coordinate order is always (lat, lng) (latitude first, in degrees).
• H3 resolutions are integers 0..15; a larger resolution is finer.
• Validate a cell/index before expensive navigation or measurement. Predicates return False for malformed or wrong-kind values; operational functions raise an H3 exception instead of silently accepting them.
• Outputs from grid, child, compact, pentagon, and edge enumerations have no guaranteed order unless stated otherwise. Compare them as sets when order is not part of the task.
• For representation, performance, NumPy/memoryview choices, or integer API calls, use api-variants; this route stays with default string behavior.
• For polygon/GeoJSON shape construction or shape-to-cells, use polygon-geospatial.
• See the root h3-py route for installation and global routing guidance.

Standard operating procedure

1. Normalize the task: point(s), target resolution, cell(s), requested relation, measurement unit, and expected output shape.
2. Use latlng_to_cell(lat, lng, res) for a point, then check is_valid_cell(cell) and get_resolution(cell).
3. Before hierarchy/grid calls, require cells at the intended resolution and verify that requested parent/child resolutions are legal. For a collection, inspect every member; compact_cells requires one common resolution.
4. Use the smallest operation that matches the task: grid_disk for filled neighborhoods, grid_ring for an exact shell, grid_path_cells for an ordered shortest path, and grid_distance for a scalar distance.
5. For a directed edge, confirm are_neighbor_cells(origin, destination) or catch H3NotNeighborsError; validate the resulting edge separately.
6. For vertices, use cell_to_vertexes rather than assuming six vertices; pentagons have five. For local IJ, keep one origin and the same resolution.
7. Measure with explicit units (km, m, rads; areas use km^2, m^2, rads^2) when output leaves the immediate call site.
8. Record the API call, resolution, coordinate order, unit, and any caught exception so a result can be reproduced without the source checkout.

Quick checks

import h3

cell = h3.latlng_to_cell(37.7752702151959, -122.418307270836, 9)
assert cell == "8928308280fffff"
assert h3.is_valid_index(cell) and h3.is_valid_cell(cell)
assert h3.get_resolution(cell) == 9
assert h3.cell_to_latlng(cell)[0] == 37.77670234943567

For a deterministic package check, run the bundled helper:

python scripts/smoke_core.py --help
python scripts/smoke_core.py check

Read api-reference.md for the supported surface, workflows.md for copyable recipes, and troubleshooting.md before retrying a failure.

Acceptance checklist

• [ ] The input uses (lat, lng), not (lng, lat).
• [ ] Every cell/edge/vertex passed to an operation has the correct kind and passes its corresponding is_valid_* predicate.
• [ ] Resolution transitions are monotonic and within 0..15.
• [ ] Grid/path operations use same-resolution cells and an affordable k.
• [ ] Collections are not accidentally supplied as one string.
• [ ] A unit is valid for the requested quantity and is stated in the result.
• [ ] Pentagon behavior is accounted for where a fixed six-neighbor or six-vertex assumption would be unsafe.
• [ ] Unordered output is normalized before comparison or serialization.

Failure recovery

• H3CellInvalidError, H3IndexInvalidError, or a False predicate result: stop and repair the index source; do not coerce a random hexadecimal string.
• H3ResDomainError or H3ResMismatchError: inspect both resolutions and choose a parent/child target in range; grid paths and local IJ require the same resolution.
• H3NotNeighborsError: test adjacency and reverse the edge direction only when the requested direction is actually intended.
• H3FailedError during distance/local IJ/path: reduce the geographic span or choose a known same-face neighborhood; the operation can be undefined or too far to compute, not evidence that the indexes are invalid.
• ValueError for a unit: use only the documented units in api-reference.md.
• Import or missing-package failures: follow the root installation route, then rerun smoke_core.py check before diagnosing H3 data.