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.

is_valid_vertex(v)

Validates an H3 vertex.

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.

cell_to_children_size(h[, res])

Number of children at resolution res of given cell.

cell_to_child_pos(child, res_parent)

Child position index of given cell, with respect to its parent at res_parent.

child_pos_to_cell(parent, res_child, child_pos)

Get child H3 cell from a parent cell, child resolution, and child position index.

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.

directed_edge_to_cells(e)

Return (origin, destination) tuple from H3 directed edge

get_directed_edge_origin(e)

Origin cell from an H3 directed edge.

get_directed_edge_destination(e)

Destination cell from an H3 directed edge.

origin_to_directed_edges(origin)

Return all directed edges starting from origin cell.

Vertexes#

cell_to_vertex(h, vertex_num)

Return a (specified) vertex of an H3 cell.

cell_to_vertexes(h)

Return a list of vertexes of an H3 cell.

vertex_to_latlng(v)

Return latitude and longitude of a vertex.

Polygon interface#

The LatLngPoly and LatLngMultiPoly 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 LatLngPoly and LatLngMultiPoly.

LatLngPoly(outer, *holes)

Container for loops of lat/lng points describing a polygon, possibly with holes.

LatLngMultiPoly(*polys)

Container for multiple LatLngPoly 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 LatLngPoly or LatLngMultiPoly.

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.