API Quick Reference

Tip

Function names changed significantly with h3-py v4.0 to align with the C library: https://h3geo.org/docs/library/migration-3.x/functions

We list the functions that are shared between the provided APIs. The APIs differ only in their input/output types (e.g., int vs. str or list vs numpy.array).

These functions correspond to those explained in the H3 C library documentation, and should be generally aligned with the other language bindings.

Identification

is_valid_cell(h)	Validates an H3 cell (hexagon or pentagon).
is_pentagon(h)	Identify if an H3 cell is a pentagon.
is_res_class_III(h)	Determine if cell has orientation "Class II" or "Class III".
is_valid_directed_edge(edge)	Validates an H3 unidirectional edge.

Index representation

int_to_str(x)	Converts an H3 64-bit integer index to a hexadecimal string.
str_to_int(h)	Converts a hexadecimal string to an H3 64-bit integer index.

Cell properties

get_res0_cells()	Return all cells at resolution 0.
get_pentagons(res)	Return all pentagons at a given resolution.
get_num_cells(res)	Return the total number of cells (hexagons and pentagons) for the given resolution.
get_resolution(h)	Return the resolution of an H3 cell.
get_base_cell_number(h)	Return the base cell number (0 to 121) of the given cell.

Geographic coordinates

Functions relating H3 objects to geographic (lat/lng) coordinates.

latlng_to_cell(lat, lng, res)	Return the cell containing the (lat, lng) point for a given resolution.
cell_to_latlng(h)	Return the center point of an H3 cell as a lat/lng pair.
cell_area(h[, unit])	Compute the spherical surface area of a specific H3 cell.
edge_length(e[, unit])	Compute the spherical length of a specific H3 edge.
cell_to_boundary(h)	Return tuple of lat/lng pairs describing the cell boundary.
directed_edge_to_boundary(edge)	Returns points representing the edge (line of points describing the boundary between two cells).
great_circle_distance(latlng1, latlng2[, unit])	Compute the spherical distance between two (lat, lng) points.
average_hexagon_area(res[, unit])	Return the average area of an H3 hexagon for the given resolution.
average_hexagon_edge_length(res[, unit])	Return the average hexagon edge length for the given resolution.

Hierarchical relationships

cell_to_parent(h[, res])	Get the parent of a cell.
cell_to_children(h[, res])	Children of a cell as an unordered collection.
cell_to_center_child(h[, res])	Get the center child of a cell at some finer resolution.
compact_cells(cells)	Compact a collection of H3 cells by combining smaller cells into larger cells, if all child cells are present.
uncompact_cells(cells, res)	Reverse the compact_cells operation.

Cell grid relationships

grid_ring(h[, k])	Return unordered collection of cells with grid distance == k from h.
grid_disk(h[, k])	Return unordered collection of cells with grid distance <= k from h.
grid_distance(h1, h2)	Compute the grid distance between two cells.
are_neighbor_cells(h1, h2)	Returns True if h1 and h2 are neighboring cells.
grid_path_cells(start, end)	Returns the ordered collection of cells denoting a minimum-length non-unique path between cells.

Edges

cells_to_directed_edge(origin, destination)	Create an H3 Index denoting a unidirectional edge.
get_directed_edge_destination(e)	Destination cell from an H3 directed edge.
directed_edge_to_cells(e)	Return (origin, destination) tuple from H3 directed edge
origin_to_directed_edges(origin)	Return all directed edges starting from origin cell.
get_directed_edge_origin(e)	Origin cell from an H3 directed edge.

Polygon interface

The H3Poly and H3MultiPoly objects and their related functions allow users to represent (multi)polygons of lat/lng points and convert back and forth between H3 cells.

The objects and functions also compatible with the popular __geo_interface__ protocol, which is used by Python geospatial libraries like GeoPandas and many plotting libraries.

See the polygon tutorial for a walkthrough.

Tip

As with other h3-py functions, the polygon interface expects coordinate pairs in lat/lng order. Note that this is reversed from __geo_interface__ objects, which are given in lng/lat order.

Polygon objects

H3Shape()	Abstract parent class of H3Poly and H3MultiPoly.
H3Poly(outer, *holes)	Container for loops of lat/lng points describing a polygon, possibly with holes.
H3MultiPoly(*polys)	Container for multiple H3Poly polygons.

Conversion functions

h3shape_to_geo(h3shape)	Translate from an H3Shape to a __geo_interface__ dict.
geo_to_h3shape(geo)	Translate from __geo_interface__ to H3Shape.
h3shape_to_cells(h3shape, res)	Return the collection of H3 cells at a given resolution whose center points are contained within an H3Poly or H3MultiPoly.
cells_to_h3shape(cells[, tight])	Return an H3Shape describing the area covered by a collection of H3 cells.
geo_to_cells(geo, res)	Convert from __geo_interface__ to cells.
cells_to_geo(cells[, tight])	Convert from cells to a __geo_interface__ dict.

Specialized functions

h3-py library

versions()

Version numbers for the Python (wrapper) and C (wrapped) libraries.

IJ-indexing

get_icosahedron_faces(h)	Return icosahedron faces intersecting a given H3 cell.
cell_to_local_ij(origin, h)	Return local (i,j) coordinates of cell h in relation to origin cell
local_ij_to_cell(origin, i, j)	Return cell at local (i,j) position relative to the origin cell.