H3 Python Bindings

4.4.2 · active · verified Thu Apr 09

h3 is a set of Python bindings for Uber's H3 C library, a hierarchical hexagonal geospatial indexing system. It allows for efficient spatial indexing, querying, and analysis using hexagonal grids. The current version is 4.4.2, and it typically sees multiple releases per year, often in sync with updates to the underlying H3 C library.

Warnings

breaking Future versions of h3-py (e.g., v4.5.0 stable) will drop support for Python 3.8 and 3.9. The minimum supported Python version will be 3.10.
Fix: Ensure your project is running on Python 3.10 or newer before upgrading to h3-py v4.5.0 or later.
breaking The functions `cells_to_h3shape` and `cells_to_geo` will become stricter in their input validation. Supplying duplicate cells will now raise an `H3DuplicateInputError`, and supplying cells of mixed resolutions will raise an `H3ResMismatchError`.
Fix: Before passing cell sets to `cells_to_h3shape` or `cells_to_geo`, ensure all cells are unique and of the same resolution to avoid runtime errors.
gotcha Prior to v4.5.0a2, `cells_to_h3shape` and `cells_to_geo` could produce incorrect results or fail silently for polygons that cross the antimeridian or poles, or for very large polygons. While newer versions fix this behavior, they also introduce stricter input validation (see breaking change above).
Fix: For critical applications involving global polygons, upgrade to v4.5.0 or newer and ensure your input cell sets are valid according to the new strict validation rules (unique and same resolution).

Install

pip install h3 Install h3

Imports

h3
```
import h3
```

Quickstart

This quickstart demonstrates how to convert geographic coordinates to an H3 index, retrieve its center and boundary, find its neighbors, and validate an H3 index.

import h3

# Example coordinates: San Francisco
lat, lon = 37.7749, -122.4194

# 1. Get an H3 index for a given lat/lon at a specific resolution
resolution = 9
h3_index = h3.geo_to_h3(lat, lon, resolution)
print(f"H3 Index for ({lat}, {lon}) at resolution {resolution}: {h3_index}")

# 2. Get the geographic coordinates of the center of an H3 index
center_coords = h3.h3_to_geo(h3_index)
print(f"Center coordinates of {h3_index}: {center_coords}")

# 3. Get the boundary (polygon) of an H3 index
boundary = h3.h3_to_geo_boundary(h3_index)
print(f"Boundary of {h3_index} (first 2 points): {boundary[:2]}...")

# 4. Find immediate neighbors of an H3 index (k-ring with distance 1)
neighbors = h3.h3_k_ring(h3_index, 1)
print(f"Neighbors of {h3_index}: {list(neighbors)}")

# 5. Check if an H3 index is valid
is_valid = h3.h3_is_valid(h3_index)
print(f"Is {h3_index} valid? {is_valid}")

view raw JSON →