API reference#
This page lists the functions that are common to each of the
provided APIs.
The APIs differ only in their input/output types
(e.g., int
vs. str
or set
vs numpy.array
).
These functions align with those explained in the core H3 documentation.
Summaries#
There is no strict hierarchy for H3 functions, but we’ll try to group functions in a reasonably logical manner.
Identification#
Validates an H3 cell (hexagon or pentagon). 


Identify if an H3 cell is a pentagon. 
Determine if cell has orientation "Class II" or "Class III". 


Validates an H3 unidirectional edge. 

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

Return the cell containing the (lat, lng) point for a given resolution. 
Return the center point of an H3 cell as a lat/lng pair. 


Converts an H3 64bit integer index to a hexadecimal string. 

Converts a hexadecimal string to an H3 64bit integer index. 
Return all cells at resolution 0. 


Return all pentagons at a given resolution. 

Return the total number of cells (hexagons and pentagons) for the given resolution. 
Return the resolution of an H3 cell. 


Compact a collection of H3 cells by combining smaller cells into larger cells, if all child cells are present. 

Reverse the compact_cells operation. 
Geographic coordinates#
Functions relating H3 objects to geographic (lat/lng) coordinates.

Compute the spherical distance between two (lat, lng) points. 

Return the average area of an H3 hexagon for the given resolution. 

Compute the spherical surface area of a specific H3 cell. 

Compute the spherical length of a specific H3 edge. 

Return the average hexagon edge length for the given resolution. 

Return tuple of lat/lng pairs describing the cell boundary. 



Return the set of H3 cells at a given resolution whose center points are contained within a h3.Polygon 

Return a list of h3.Polygon objects describing the area covered by a set of H3 cells. 
Hierarchical relationships#

Get the parent of a cell. 

Children of a cell. 

Get the center child of a cell at some finer resolution. 
Cell grid relationships#

Return unordered set of cells with H3 distance 

Return unordered set of cells with H3 distance 

Compute the H3 distance between two cells. 

Returns 

Returns the ordered collection of cells denoting a minimumlength nonunique path between cells. 
Edges#

Create an H3 Index denoting a unidirectional edge. 
Destination cell from an H3 directed edge. 

Return (origin, destination) tuple from H3 directed edge 


Return all directed edges starting from 
Origin cell from an H3 directed edge. 
IJindexing#
Return the base cell number ( 

Return icosahedron faces intersecting a given H3 cell. 


Return local (i,j) coordinates of cell 

Return cell at local (i,j) position relative to the 
Definitions#
 exception h3.H3BaseException#
Base H3 exception class.
Concrete subclasses of this class correspond to specific error codes from the C library.
Base/abstract subclasses will have h3_error_code = None, while concrete subclasses will have h3_error_code equal to their associated C library error code.
 exception h3.H3CellInvalidError#
 exception h3.H3DirEdgeInvalidError#
 exception h3.H3DomainError#
 exception h3.H3DuplicateInputError#
 exception h3.H3FailedError#
 exception h3.H3LatLngDomainError#
 exception h3.H3MemoryAllocError#
 exception h3.H3MemoryBoundsError#
 exception h3.H3MemoryError#
 exception h3.H3NotNeighborsError#
 exception h3.H3OptionInvalidError#
 exception h3.H3PentagonError#
 exception h3.H3ResDomainError#
 exception h3.H3ResMismatchError#
 exception h3.H3UndirEdgeInvalidError#
 exception h3.H3ValueError#
 exception h3.H3VertexInvalidError#
 class h3.Polygon(outer, *holes)[source]#
Container for loops of lat/lng points describing a polygon.
 outer#
List of lat/lng points describing the outer loop of the Polygon
 Type:
list[tuple[float, float]]
 holes#
List of loops of lat/lng points describing the holes of the Polygon
 Type:
list[list[tuple[float, float]]]
Examples
A polygon with a single outer ring consisting of 4 points, having no holes:
>>> h3.Polygon( ... [(37.68, 122.54), (37.68, 122.34), (37.82, 122.34), (37.82, 122.54)], ... ) <h3.Polygon outer=4, holes=()>
The same polygon, but with one hole consisting of 3 points:
>>> h3.Polygon( ... [(37.68, 122.54), (37.68, 122.34), (37.82, 122.34), (37.82, 122.54)], ... [(37.76, 122.51), (37.76, 122.44), (37.81, 122.51)], ... ) <h3.Polygon outer=4, holes=(3,)>
The same as above, but with one additional hole, made up of 5 points:
>>> h3.Polygon( ... [(37.68, 122.54), (37.68, 122.34), (37.82, 122.34), (37.82, 122.54)], ... [(37.76, 122.51), (37.76, 122.44), (37.81, 122.51)], ... [(37.71, 122.43), (37.71, 122.37), (37.73, 122.37), (37.75, 122.41), ... (37.73, 122.43)], ... ) <h3.Polygon outer=4, holes=(3, 5)>
Notes
TODO: Add GeoJSON translation support.
 exception h3.UnknownH3ErrorCode#
Indicates that the h3py Python bindings have received an unrecognized error code from the C library.
This should never happen. Please report if you get this error.
Note that this exception is outside of the H3BaseException class hierarchy.
 h3.are_neighbor_cells(h1, h2)#
Returns
True
ifh1
andh2
are neighboring cells. Parameters:
h1 (H3Cell) –
h2 (H3Cell) –
 Return type:
bool
 h3.average_hexagon_area(res, unit='km^2')#
Return the average area of an H3 hexagon for the given resolution.
This average excludes pentagons.
 Return type:
float
 h3.average_hexagon_edge_length(res, unit='km')#
Return the average hexagon edge length for the given resolution.
This average excludes pentagons.
 Return type:
float
 h3.cell_area(h, unit='km^2')#
Compute the spherical surface area of a specific H3 cell.
 Parameters:
h (H3Cell) –
unit (str) – Unit for area result (
'km^2'
, ‘m^2’, or ‘rads^2’)
 Return type:
The area of the H3 cell in the given units
Notes
This function breaks the cell into spherical triangles, and computes their spherical area. The function uses the spherical distance calculation given by great_circle_distance.
 h3.cell_to_boundary(h, geo_json=False)#
Return tuple of lat/lng pairs describing the cell boundary.
 Parameters:
h (H3Cell) –
geo_json (bool, optional) – If
True
, return output in GeoJson format: lng/lat pairs (opposite order), and have the last pair be the same as the first. IfFalse
(default), return lat/lng pairs, with the last pair distinct from the first.
 Return type:
tuple of (float, float) tuples
 h3.cell_to_center_child(h, res=None)#
Get the center child of a cell at some finer resolution.
 Parameters:
h (H3Cell) –
res (int or None, optional) – The resolution for the child cell If
None
, thenres = resolution(h) + 1
 Return type:
H3Cell
 h3.cell_to_children(h, res=None)#
Children of a cell.
 Parameters:
h (H3Cell) –
res (int or None, optional) – The resolution for the children. If
None
, thenres = resolution(h) + 1
 Return type:
unordered collection of H3Cell
 h3.cell_to_latlng(h)#
Return the center point of an H3 cell as a lat/lng pair.
 Parameters:
h (H3Cell) –
 Returns:
lat (float) – Latitude
lng (float) – Longitude
 h3.cell_to_local_ij(origin, h)#
Return local (i,j) coordinates of cell
h
in relation toorigin
cell Parameters:
origin (H3Cell) – Origin/central cell for defining i,j coordinates.
h (H3Cell) – Destination cell whose i,j coordinates we’d like, based off of the origin cell.
 Return type:
Tuple (i, j) of integer local coordinates of cell
h
Notes
The
origin
cell does not define (0, 0) for the IJ coordinate space. (0, 0) refers to the center of the base cell containing origin at the resolution of origin. Subtracting the IJ coordinates oforigin
from every cell would get you the property of (0, 0) being theorigin
.This is done so we don’t need to keep recomputing the coordinates of
origin
if not needed.
 h3.cell_to_parent(h, res=None)#
Get the parent of a cell.
 Parameters:
h (H3Cell) –
res (int or None, optional) – The resolution for the parent If
None
, thenres = resolution(h)  1
 Return type:
H3Cell
 h3.cells_to_directed_edge(origin, destination)#
Create an H3 Index denoting a unidirectional edge.
The edge is constructed from neighboring cells
origin
anddestination
. Parameters:
origin (H3Cell) –
destination (H3Cell) –
 Raises:
ValueError – When cells are not adjacent.
 Return type:
H3Edge
 h3.cells_to_polygons(cells)#
Return a list of h3.Polygon objects describing the area covered by a set of H3 cells.
 Parameters:
cells (iterable of H3 cells) –
 Returns:
List of h3.Polygon objects
 Return type:
list[h3.Polygon]
Examples
>>> cells = ['8428309ffffffff', '842830dffffffff'] >>> h3.cells_to_polygons(cells) [<h3.Polygon outer=10, holes=()>]
 h3.compact_cells(cells)#
Compact a collection of H3 cells by combining smaller cells into larger cells, if all child cells are present. Input cells must all share the same resolution.
 Parameters:
cells (iterable of H3 Cells) –
 Return type:
unordered collection of H3Cell
 h3.directed_edge_to_cells(e)#
Return (origin, destination) tuple from H3 directed edge
 Parameters:
e (H3Edge) –
 Returns:
H3Cell – Origin cell of edge
H3Cell – Destination cell of edge
 h3.edge_length(e, unit='km')#
Compute the spherical length of a specific H3 edge.
 Parameters:
h (H3Cell) –
unit (str) – Unit for length result (‘km’, ‘m’, or ‘rads’)
 Return type:
The length of the edge in the given units
Notes
This function uses the spherical distance calculation given by great_circle_distance.
 h3.get_base_cell_number(h)#
Return the base cell number (
0
to121
) of the given cell.The base cell number and the H3Index are two different representations of the same cell: the parent cell of resolution
0
.The base cell number is encoded within the corresponding H3Index.
todo: could work with edges
 Parameters:
h (H3Cell) –
 Return type:
int
 h3.get_directed_edge_destination(e)#
Destination cell from an H3 directed edge.
 Parameters:
e (H3Edge) –
 Return type:
H3Cell
 h3.get_directed_edge_origin(e)#
Origin cell from an H3 directed edge.
 Parameters:
e (H3Edge) –
 Return type:
H3Cell
 h3.get_icosahedron_faces(h)#
Return icosahedron faces intersecting a given H3 cell.
There are twenty possible faces, ranging from 0–19.
Note: Every interface returns a Python
set
ofint
. Parameters:
h (H3Cell) –
 Return type:
Python
set
ofint
 h3.get_num_cells(res)#
Return the total number of cells (hexagons and pentagons) for the given resolution.
 Return type:
int
 h3.get_pentagons(res)#
Return all pentagons at a given resolution.
 Parameters:
res (int) – Resolution of the pentagons
 Return type:
unordered collection of H3Cell
 h3.get_res0_cells()#
Return all cells at resolution 0.
 Parameters:
None –
 Return type:
unordered collection of H3Cell
 h3.get_resolution(h)#
Return the resolution of an H3 cell.
 Parameters:
h (H3Cell) –
 Return type:
int
 h3.great_circle_distance(latlng1, latlng2, unit='km')#
Compute the spherical distance between two (lat, lng) points. AKA: great circle distance or “haversine” distance.
todo: overload to allow two cell inputs?
 Parameters:
latlng1 (tuple) – (lat, lng) tuple in degrees
latlng2 (tuple) – (lat, lng) tuple in degrees
unit (str) – Unit for distance result (‘km’, ‘m’, or ‘rads’)
 Return type:
The spherical distance between the points in the given units
 h3.grid_disk(h, k=1)#
Return unordered set of cells with H3 distance
<= k
fromh
. That is, the “filledin” disk. Parameters:
h (H3Cell) –
k (int) – Size of disk.
 Return type:
unordered collection of H3Cell
 h3.grid_distance(h1, h2)#
Compute the H3 distance between two cells.
The H3 distance is defined as the length of the shortest path between the cells in the graph formed by connecting adjacent cells.
This function will raise an exception if the cells are too far apart to compute the distance.
 Parameters:
h1 (H3Cell) –
h2 (H3Cell) –
 Return type:
int
 h3.grid_path_cells(start, end)#
Returns the ordered collection of cells denoting a minimumlength nonunique path between cells.
 Parameters:
start (H3Cell) –
end (H3Cell) –
 Returns:
Starting with
start
, and ending withend
. Return type:
ordered collection of H3Cell
 h3.grid_ring(h, k=1)#
Return unordered set of cells with H3 distance
== k
fromh
. That is, the “hollow” ring. Parameters:
h (H3Cell) –
k (int) – Size of ring.
 Return type:
unordered collection of H3Cell
 h3.int_to_str(x)#
Converts an H3 64bit integer index to a hexadecimal string.
 Parameters:
x (int) – Unsigned 64bit integer
 Returns:
Hexadecimal string like
'89754e64993ffff'
 Return type:
str
 h3.is_pentagon(h)#
Identify if an H3 cell is a pentagon.
 Parameters:
h (H3Index) –
 Returns:
True
if input is a valid H3 cell which is a pentagon. Return type:
bool
Notes
A pentagon should also pass
is_valid_cell()
. Will returnFalse
for valid H3Edge.
 h3.is_res_class_III(h)#
Determine if cell has orientation “Class II” or “Class III”.
The orientation of pentagons/hexagons on the icosahedron can be one of two types: “Class II” or “Class III”.
All cells within a resolution have the same type, and the type alternates between resolutions.
“Class II” cells have resolutions: 0,2,4,6,8,10,12,14 “Class III” cells have resolutions: 1,3,5,7,9,11,13,15
 Parameters:
h (H3Cell) –
 Returns:
True
ifh
is “Class III”.False
ifh
is “Class II”. Return type:
bool
References
 h3.is_valid_cell(h)#
Validates an H3 cell (hexagon or pentagon).
 Return type:
bool
 h3.is_valid_directed_edge(edge)#
Validates an H3 unidirectional edge.
 Return type:
bool
 h3.latlng_to_cell(lat, lng, res)#
Return the cell containing the (lat, lng) point for a given resolution.
 Return type:
H3Cell
 h3.local_ij_to_cell(origin, i, j)#
Return cell at local (i,j) position relative to the
origin
cell. Parameters:
origin (H3Cell) – Origin/central cell for defining i,j coordinates.
i (int) – Integer coordinates with respect to
origin
cell.j (int) – Integer coordinates with respect to
origin
cell.
 Return type:
H3Cell at local (i,j) position relative to the
origin
cell
Notes
The
origin
cell does not define (0, 0) for the IJ coordinate space. (0, 0) refers to the center of the base cell containing origin at the resolution oforigin
. Subtracting the IJ coordinates oforigin
from every cell would get you the property of (0, 0) being theorigin
.This is done so we don’t need to keep recomputing the coordinates of
origin
if not needed.
 h3.origin_to_directed_edges(origin)#
Return all directed edges starting from
origin
cell. Parameters:
origin (H3Cell) –
 Return type:
unordered collection of H3Edge
 h3.polygon_to_cells(polygon, res)#
Return the set of H3 cells at a given resolution whose center points are contained within a h3.Polygon
 Parameters:
Polygon (h3.Polygon) – A polygon described by an outer ring and optional holes
res (int) – Resolution of the output cells
Examples
>>> poly = h3.Polygon( ... [(37.68, 122.54), (37.68, 122.34), (37.82, 122.34), ... (37.82, 122.54)], ... ) >>> h3.polygon_to_cells(poly, 6) {'862830807ffffff', '862830827ffffff', '86283082fffffff', '862830877ffffff', '862830947ffffff', '862830957ffffff', '86283095fffffff'}
 h3.str_to_int(h)#
Converts a hexadecimal string to an H3 64bit integer index.
 Parameters:
h (str) – Hexadecimal string like
'89754e64993ffff'
 Returns:
Unsigned 64bit integer
 Return type:
int
 h3.uncompact_cells(cells, res)#
Reverse the compact_cells operation.
Return a collection of H3 cells, all of resolution
res
. Parameters:
cells (iterable of H3Cell) –
res (int) – Resolution of desired output cells.
 Return type:
unordered collection of H3Cell
 Raises:
todo – add test to make sure an error is returned when input:
contains cell smaller than output res. –
https://github.com/uber/h3/blob/master/src/h3lib/lib/h3Index.c#L425 –
 h3.versions()#
Version numbers for the Python (wrapper) and C (wrapped) libraries.
Versions are output as strings of the form
'X.Y.Z'
. C and Python should match onX
(major) andY
(minor), but may differ onZ
(patch). Return type:
dict like
{'c': 'X.Y.Z', 'python': 'A.B.C'}