API Verbose Reference#
This page gives the full documentation for each function and object. Refer back to API Quick Reference for context and logical groupings.
- 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.LatLngMultiPoly(*polys)[source]#
Container for multiple
LatLngPoly
polygons.- polys#
List of lat/lng points describing the outer loop of the polygon
- Type:
list[LatLngPoly]
- class h3.LatLngPoly(outer, *holes)[source]#
Container for loops of lat/lng points describing a polygon, possibly with holes.
- 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:
>>> LatLngPoly( ... [(37.68, -122.54), (37.68, -122.34), (37.82, -122.34), (37.82, -122.54)], ... ) <LatLngPoly: [4]>
The same polygon, but with one hole consisting of 3 points:
>>> LatLngPoly( ... [(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)], ... ) <LatLngPoly: [4/(3,)]>
The same as above, but with one additional hole, made up of 5 points:
>>> LatLngPoly( ... [(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)], ... ) <LatLngPoly: [4/(3, 5)]>
- property loopcode#
Short code for describing the length of the outer loop and each hole
Example:
[382/(18, 6, 6)]
indicates an outer loop of 382 points, along with 3 holes with 18, 6, and 6 points, respectively.Example:
[15]
indicates an outer loop of 15 points and no holes.
- exception h3.UnknownH3ErrorCode#
Indicates that the h3-py 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)[source]#
Returns
True
ifh1
andh2
are neighboring cells.- Parameters:
h1 (H3Cell)
h2 (H3Cell)
- Return type:
bool
- h3.average_hexagon_area(res, unit='km^2')[source]#
Return the average area of an H3 hexagon for the given resolution.
This average excludes pentagons.
- Parameters:
res (int) – H3 resolution
unit (str) – Unit for area result (
'km^2'
,'m^2'
, or'rads^2'
)
- Return type:
float
- h3.average_hexagon_edge_length(res, unit='km')[source]#
Return the average hexagon edge length for the given resolution.
This average excludes pentagons.
- Parameters:
res (int) – H3 resolution
unit (str) – Unit for length result (
'km'
,'m'
, or'rads'
)
- Return type:
float
- h3.cell_area(h, unit='km^2')[source]#
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)[source]#
Return tuple of lat/lng pairs describing the cell boundary.
- Parameters:
h (H3Cell)
- Return type:
tuple of (lat, lng) tuples
- h3.cell_to_center_child(h, res=None)[source]#
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_child_pos(child, res_parent)[source]#
Child position index of given cell, with respect to its parent at
res_parent
.The reverse operation can be done with
child_pos_to_cell
.- Parameters:
child (H3Cell)
res_parent (int)
- Returns:
Integer index of the child with respect to parent cell.
- Return type:
int
- h3.cell_to_children(h, res=None)[source]#
Children of a cell as an unordered collection.
- 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
Notes
There is currently no guaranteed order of the output cells.
- h3.cell_to_children_size(h, res=None)[source]#
Number of children at resolution
res
of given cell.- Parameters:
h (H3Cell)
res (int or None, optional) – The resolution for the children. If
None
, thenres = resolution(h) + 1
- Returns:
Count of children
- Return type:
int
- h3.cell_to_latlng(h)[source]#
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)[source]#
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)[source]#
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.cell_to_vertex(h, vertex_num)[source]#
Return a (specified) vertex of an H3 cell.
- Parameters:
h (H3Cell)
vertex_num (int) – Vertex number (0-5)
- Return type:
The vertex
- h3.cell_to_vertexes(h)[source]#
Return a list of vertexes of an H3 cell. The list will be of length 5 for pentagons and 6 for hexagons.
- Parameters:
h (H3Cell)
- Return type:
A list of vertexes
- h3.cells_to_directed_edge(origin, destination)[source]#
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_geo(cells, tight=True)[source]#
Convert from cells to a
__geo_interface__
dict.- Parameters:
cells (iterable of H3 Cells)
tight (bool) – When
True
, returns anLatLngPoly
when possible. WhenFalse
, always returns anLatLngMultiPoly
.
- Returns:
in __geo_interface__ format
- Return type:
dict
- h3.cells_to_h3shape(cells, *, tight=True)[source]#
Return an
H3Shape
describing the area covered by a collection of H3 cells. Will returnLatLngPoly
orLatLngMultiPoly
.- Parameters:
cells (iterable of H3 cells)
tight (bool) – If True, return
LatLngPoly
if possible. If False, always returnLatLngMultiPoly
.
- Return type:
Examples
>>> cells = ['8428309ffffffff', '842830dffffffff'] >>> h3.cells_to_h3shape(cells, tight=True) <LatLngPoly: [10]> >>> h3.cells_to_h3shape(cells, tight=False) <LatLngMultiPoly: [10]>
- h3.child_pos_to_cell(parent, res_child, child_pos)[source]#
Get child H3 cell from a parent cell, child resolution, and child position index.
The reverse operation can be done with
cell_to_child_pos
.- Parameters:
parent (H3Cell)
res_child (int) – Child cell resolution
child_pos (int) – Integer position of child cell, releative to parent.
- Return type:
H3Cell
- h3.compact_cells(cells)[source]#
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
Notes
There is currently no guaranteed order of the output cells.
- h3.directed_edge_to_boundary(edge)[source]#
Returns points representing the edge (line of points describing the boundary between two cells).
- Parameters:
edge (H3Edge)
- Return type:
tuple of (lat, lng) tuples
- h3.directed_edge_to_cells(e)[source]#
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')[source]#
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.geo_to_cells(geo, res)[source]#
Convert from
__geo_interface__
to cells.- Parameters:
geo (an object implementing
__geo_interface__
or a dictionary in that format.) – BothLatLngPoly
andLatLngMultiPoly
implement the interface.res (int) – Resolution of desired output cells.
Notes
There is currently no guaranteed order of the output cells.
- h3.geo_to_h3shape(geo)[source]#
Translate from
__geo_interface__
to H3Shape.geo
either implements__geo_interface__
or is a dict matching the format- Return type:
- h3.get_base_cell_number(h)[source]#
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)[source]#
Destination cell from an H3 directed edge.
- Parameters:
e (H3Edge)
- Return type:
H3Cell
- h3.get_directed_edge_origin(e)[source]#
Origin cell from an H3 directed edge.
- Parameters:
e (H3Edge)
- Return type:
H3Cell
- h3.get_icosahedron_faces(h)[source]#
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)[source]#
Return the total number of cells (hexagons and pentagons) for the given resolution.
- Return type:
int
- h3.get_pentagons(res)[source]#
Return all pentagons at a given resolution.
- Parameters:
res (int) – Resolution of the pentagons
- Return type:
unordered collection of H3Cell
- h3.get_res0_cells()[source]#
Return all cells at resolution 0.
- Parameters:
None
- Return type:
unordered collection of H3Cell
Notes
There is currently no guaranteed order of the output cells.
- h3.get_resolution(h)[source]#
Return the resolution of an H3 cell.
- Parameters:
h (H3Cell)
- Return type:
int
- h3.great_circle_distance(latlng1, latlng2, unit='km')[source]#
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)[source]#
Return unordered collection of cells with grid distance
<= k
fromh
. That is, the “filled-in” disk.- Parameters:
h (H3Cell)
k (int) – Size of disk.
- Return type:
unordered collection of H3Cell
Notes
There is currently no guaranteed order of the output cells.
- h3.grid_distance(h1, h2)[source]#
Compute the grid distance between two cells.
The grid 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)[source]#
Returns the ordered collection of cells denoting a minimum-length non-unique 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)[source]#
Return unordered collection of cells with grid distance
== k
fromh
. That is, the “hollow” ring.- Parameters:
h (H3Cell)
k (int) – Size of ring.
- Return type:
unordered collection of H3Cell
Notes
There is currently no guaranteed order of the output cells.
- h3.h3shape_to_cells(h3shape, res)[source]#
Return the collection of H3 cells at a given resolution whose center points are contained within an
LatLngPoly
orLatLngMultiPoly
.- Parameters:
h3shape (
H3Shape
)res (int) – Resolution of the output cells
- Return type:
list of H3Cell
Examples
>>> poly = LatLngPoly( ... [(37.68, -122.54), (37.68, -122.34), (37.82, -122.34), ... (37.82, -122.54)], ... ) >>> h3.h3shape_to_cells(poly, 6) ['862830807ffffff', '862830827ffffff', '86283082fffffff', '862830877ffffff', '862830947ffffff', '862830957ffffff', '86283095fffffff']
Notes
There is currently no guaranteed order of the output cells.
- h3.h3shape_to_geo(h3shape)[source]#
Translate from an
H3Shape
to a__geo_interface__
dict.h3shape
should be eitherLatLngPoly
orLatLngMultiPoly
- Return type:
dict
- h3.int_to_str(x)[source]#
Converts an H3 64-bit integer index to a hexadecimal string.
- Parameters:
x (int) – Unsigned 64-bit integer
- Returns:
Hexadecimal string like
'89754e64993ffff'
- Return type:
str
- h3.is_pentagon(h)[source]#
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)[source]#
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.latlng_to_cell(lat, lng, res)[source]#
Return the cell containing the (lat, lng) point for a given resolution.
- Return type:
H3Cell
- h3.local_ij_to_cell(origin, i, j)[source]#
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)[source]#
Return all directed edges starting from
origin
cell.- Parameters:
origin (H3Cell)
- Return type:
unordered collection of H3Edge
- h3.str_to_int(h)[source]#
Converts a hexadecimal string to an H3 64-bit integer index.
- Parameters:
h (str) – Hexadecimal string like
'89754e64993ffff'
- Returns:
Unsigned 64-bit integer
- Return type:
int
- h3.uncompact_cells(cells, res)[source]#
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
Notes
There is currently no guaranteed order of the output cells.