---

name: h3-py description: "Use Uber's h3 Python bindings for hierarchical hexagonal geospatial indexing, cell/grid/edge operations, polygon and GeoJSON conversion, and string/integer/NumPy API selection." disable-model-invocation: true metadata: disco-role: operating license: Apache 2.0

h3-py

Use this skill when a task needs H3 geospatial indexing from Python: map a latitude/longitude to a cell, inspect or navigate cells, measure spherical quantities, index polygons, convert GeoJSON-like objects, or choose between H3's string, integer, memoryview, and NumPy interfaces.

Install and verify

The public distribution is h3 and requires Python 3.10 or newer. It has no runtime dependency for the default string or memoryview APIs:

python -m pip install h3
python -c "import h3; print(h3.versions())"

Install the optional NumPy API explicitly when downstream code needs h3.api.numpy_int:

python -m pip install 'h3[numpy]'

For a fuller deterministic check, run the bundled helper check_h3_environment.py. Read installation.md for source-build, version, and optional-dependency details. Read troubleshooting.md before treating an import or input error as an H3 algorithm failure.

Route the task

• Point, cell, hierarchy, grid, measurement, edge, vertex, or local-IJ work: read core-indexing.
• Polygon, hole, multipolygon, GeoJSON, __geo_interface__, or CRS work: read polygon-geospatial.
• String versus integer indexes, NumPy arrays, memoryview buffers, conversions, or API performance trade-offs: read api-variants.

A task can use multiple routes. For example, index a polygon with polygon-geospatial, then use core-indexing to inspect or compact the returned cells; choose api-variants only at a representation boundary.

Shared operating contract

1. Treat geographic pairs as (lat, lng) in degrees for H3 calls. GeoJSON positions are (lng, lat) and must be swapped exactly once at the boundary.
2. Make the resolution explicit. H3 resolutions are integers 0..15; larger values represent finer cells.
3. Validate the kind of every index before passing it to an operation. A cell, directed edge, and vertex are different H3 index types.
4. Do not assume enumeration order. Normalize unordered cell, edge, vertex, or pentagon results before comparison or serialization.
5. Record package version, API variant, resolution, coordinate order, units, and containment mode when a result must be reproducible.
6. Keep the original repository out of runtime workflows; use only the references and safe helpers bundled in this skill.

High-value entry points

• h3.latlng_to_cell(lat, lng, res) creates a cell from a point.
• h3.cell_to_latlng, cell_to_boundary, cell_area, and great_circle_distance recover geometry or measurements.
• h3.cell_to_parent, cell_to_children, compact_cells, and uncompact_cells handle hierarchy.
• h3.grid_disk, grid_ring, grid_distance, and grid_path_cells handle neighborhood and path operations.
• h3.LatLngPoly, h3.h3shape_to_cells, h3.geo_to_cells, and h3.cells_to_geo handle polygon workflows.
• h3.versions() reports the Python wrapper and wrapped C library versions; their major and minor versions should match.

The route-specific references contain signatures, output types, recipes, and failure recovery. Do not infer a missing argument or unit from a neighboring H3 language binding.