Region functions

These functions convert H3 indexes to and from polygonal areas.

polygonToCells

Each binding's version of polygonToCells takes as input a GeoJSON-like data structure describing a polygon (i.e., an outer ring and optional holes) and a target cell resolution. It produces a collection of cells that are contained within the polygon.

Containment is determined by centroids of the cells, so that a partitioning of polygons (covering an area without overlaps) will result in a partitioning of H3 cells.

C

H3Error polygonToCells(const GeoPolygon *geoPolygon, int res, uint32_t flags, H3Index *out);

In C, polygonToCells takes a GeoPolygon struct and preallocated, zeroed memory, and fills it with the covering cells.

Returns 0 (E_SUCCESS) on success.

Java

List<Long> polygonToCells(List<LatLng> points, List<List<LatLng>> holes, int res);
List<String> polygonToCellAddresses(List<LatLng> points, List<List<LatLng>> holes, int res);

JavaScript (Live)

h3.polygonToCells(polygon, res, isGeoJson)

Live Editor

function example() { const polygon = [ [37.813318999983238, -122.4089866999972145], [37.7198061999978478, -122.3544736999993603], [37.8151571999998453, -122.4798767000009008] ]; const res = 7; return h3.polygonToCells(polygon, res); }

function example() {
    const polygon = [
        [37.813318999983238, -122.4089866999972145],
        [37.7198061999978478, -122.3544736999993603],
        [37.8151571999998453, -122.4798767000009008]
    ];
    const res = 7;
    return h3.polygonToCells(polygon, res);
}

Result

Loading...

Python

h3.polygon_to_cells(h3shape, res)
h3.h3shape_to_cells(h3shape, res)

In Python, h3shape_to_cells takes an H3Shape object (LatLngPoly or LatLngMultiPoly). Note that polygon_to_cells is an alias for h3shape_to_cells. For more info, see the h3-py docs.

Shell

$ h3 polygonToCells --help
h3: Converts a polygon (array of lat, lng points, or array of arrays of lat, lng points) into a set of covering cells at the specified resolution
H3 4.1.0

    polygonToCells  Converts a polygon (array of lat, lng points, or array of arrays of lat, lng points) into a set of covering cells at the specified resolution
    -h, --help  Show this help message.
    -i, --file <FILENAME>   The file to load the polygon from. Use -- to read from stdin.
    -p, --polygon <POLYGON> The polygon to convert. Up to 1500 characters.
    -r, --resolution <res>  Required. Resolution, 0-15 inclusive, that the polygon should be converted to.
    -f, --format <FMT>  'json' for ["CELL", ...], 'newline' for CELL\n... (Default: json)

$ h3 polygonToCells -r 7 -p "[[37.813318999983238, -122.4089866999972145], [37.7198061999978478, -122.3544736999993603], [37.8151571999998453, -122.4798767000009008]]"
[ "87283082bffffff", "872830870ffffff", "872830820ffffff", "87283082effffff", "872830828ffffff", "87283082affffff", "872830876ffffff" ]

maxPolygonToCellsSize

Provides an upper bound on the number of cells needed for memory allocation purposes when computing polygonToCells on the given GeoJSON-like data structure.

C

H3Error maxPolygonToCellsSize(const GeoPolygon *geoPolygon, int res, uint32_t flags, int64_t *out);

Returns 0 (E_SUCCESS) on success.

Java

note

This function exists for memory management and is not exposed.

JavaScript (Live)

note

This function exists for memory management and is not exposed.

Python

note

This function exists for memory management and is not exposed.

Shell

$ h3 maxPolygonToCellsSize --help
h3: Returns the maximum number of cells that could be needed to cover the polygon. Will always be equal or more than actually necessary
H3 4.1.0

    maxPolygonToCellsSize   Returns the maximum number of cells that could be needed to cover the polygon. Will always be equal or more than actually necessary
    -h, --help  Show this help message.
    -i, --file <FILENAME>   The file to load the polygon from. Use -- to read from stdin.
    -p, --polygon <POLYGON> The polygon to convert. Up to 1500 characters.
    -r, --resolution <res>  Required. Resolution, 0-15 inclusive, that the polygon should be converted to.

$ h3 maxPolygonToCellsSize -r 7 -p "[[37.813318999983238, -122.4089866999972145], [37.7198061999978478, -122.3544736999993603], [37.8151571999998453, -122.4798767000009008]]"
100

polygonToCellsExperimental

Each binding's version of polygonToCellsExperimental takes as input a GeoJSON-like data structure describing a polygon (i.e., an outer ring and optional holes) and a target cell resolution. It produces a collection of cells that are contained within the polygon.

This function differs from polygonToCells in that it uses an experimental new algorithm which supports center-based, fully-contained, and overlapping containment modes.

C

H3Error polygonToCellsExperimental(const GeoPolygon *geoPolygon, int res, uint32_t flags, int64_t size, H3Index *out);

In C, polygonToCellsExperimental takes a GeoPolygon struct and preallocated, zeroed memory, and fills it with the covering cells.

size should be the size in number of H3Indexs of out.

The valid values for flags are:

Enum name	Integer value	Description
CONTAINMENT_CENTER	0	Cell center is contained in the shape
CONTAINMENT_FULL	1	Cell is fully contained in the shape
CONTAINMENT_OVERLAPPING	2	Cell overlaps the shape at any point
CONTAINMENT_OVERLAPPING_BBOX	3	Cell bounding box overlaps shape

Returns 0 (E_SUCCESS) on success.

Java

List<Long> polygonToCellsExperimental(List<LatLng> points, List<List<LatLng>> holes, PolygonToCellsFlags flags, int res);
List<String> polygonToCellExperimentalAddresses(List<LatLng> points, List<List<LatLng>> holes, PolygonToCellsFlags flags, int res);

The valid values for flags are:

Enum name	Description
PolygonToCellsFlags.containment_center	Cell center is contained in the shape
PolygonToCellsFlags.containment_full	Cell is fully contained in the shape
PolygonToCellsFlags.containment_overlapping	Cell overlaps the shape at any point
PolygonToCellsFlags.containment_overlapping_bbox	Cell bounding box overlaps shape

JavaScript (Live)

h3.polygonToCellsExperimental(polygon, res, flags, isGeoJson)

Live Editor

function example() { const polygon = [ [37.813318999983238, -122.4089866999972145], [37.7198061999978478, -122.3544736999993603], [37.8151571999998453, -122.4798767000009008] ]; const res = 7; return h3.polygonToCellsExperimental(polygon, h3.POLYGON_TO_CELLS_FLAGS.containmentOverlapping, res); }

function example() {
    const polygon = [
        [37.813318999983238, -122.4089866999972145],
        [37.7198061999978478, -122.3544736999993603],
        [37.8151571999998453, -122.4798767000009008]
    ];
    const res = 7;
    return h3.polygonToCellsExperimental(polygon, h3.POLYGON_TO_CELLS_FLAGS.containmentOverlapping, res);
}

Result

Loading...

The valid values for flags are:

Enum name	Description
POLYGON_TO_CELLS_FLAGS.containment_center	Cell center is contained in the shape
POLYGON_TO_CELLS_FLAGS.containment_full	Cell is fully contained in the shape
POLYGON_TO_CELLS_FLAGS.containment_overlapping	Cell overlaps the shape at any point
POLYGON_TO_CELLS_FLAGS.containment_overlapping_bbox	Cell bounding box overlaps shape

Python

h3.h3shape_to_cells_experimental(h3shape, res, contain='overlap')

In Python, h3shape_to_cells_experimental takes an H3Shape object (LatLngPoly or LatLngMultiPoly). For more info, see the h3-py docs.

The valid values for contain are:

String value	Description
center	Cell center is contained in the shape (default)
full	Cell is fully contained in the shape
overlap	Cell overlaps the shape at any point
bbox_overlap	Cell bounding box overlaps shape

Shell

This function is not exposed in the CLI bindings.

maxPolygonToCellsExperimentalSize

Provides an upper bound on the number of cells needed for memory allocation purposes when computing polygonToCellsExperimental on the given GeoJSON-like data structure.

C

H3Error maxPolygonToCellsExperimentalSize(const GeoPolygon *geoPolygon, int res, uint32_t flags, int64_t *out);

Returns 0 (E_SUCCESS) on success.

Java

note

This function exists for memory management and is not exposed.

JavaScript (Live)

note

This function exists for memory management and is not exposed.

Python

note

This function exists for memory management and is not exposed.

Shell

This function is not exposed in the CLI bindings.

cellsToLinkedMultiPolygon / cellsToMultiPolygon

Create a GeoJSON-like multi-polygon describing the outline(s) of a set of cells. Polygon outlines will follow GeoJSON MultiPolygon order: Each polygon will have one outer loop, which is first in the list, followed by any holes.

It is expected that all cells in the set have the same resolution and that the set contains no duplicates. Behavior is undefined if duplicates or multiple resolutions are present, and the algorithm may produce unexpected or invalid output.

C

H3Error cellsToLinkedMultiPolygon(const H3Index *h3Set, const int numHexes, LinkedGeoPolygon *out);

It is the responsibility of the caller to call destroyLinkedPolygon on the populated linked geo structure, or the memory for that structure will not be freed.

Returns 0 (E_SUCCESS) on success.

Java

List<List<List<LatLng>>> cellsToMultiPolygon(Collection<Long> h3, boolean geoJson);
List<List<List<LatLng>>> cellAddressesToMultiPolygon(Collection<String> h3Addresses, boolean geoJson);

JavaScript (Live)

h3.cellsToMultiPolygon(cells, geoJson)

Live Editor

function example() { const cells = ['872830828ffffff', '87283082effffff']; return h3.cellsToMultiPolygon(cells, true); }

function example() {
    const cells = ['872830828ffffff', '87283082effffff'];
    return h3.cellsToMultiPolygon(cells, true);
}

Result

Loading...

Python

h3.cells_to_h3shape(cells, *, tight=True)

Returns an H3Shape object:

• If tight=True, returns LatLngPoly if possible, otherwise LatLngMultiPoly.
• If tight=False, always returns a LatLngMultiPoly.

For more info, see the h3-py docs.

Shell

$ h3 cellsToMultiPolygon --help
h3: Returns a polygon (array of arrays of lat, lng points) for a set of cells
H3 4.1.0

    cellsToMultiPolygon Returns a polygon (array of arrays of lat, lng points) for a set of cells
    -h, --help  Show this help message.
    -i, --file <FILENAME>   The file to load the cells from. Use -- to read from stdin.
    -c, --cells <CELLS> The cells to convert. Up to 100 cells if provided as hexadecimals with zero padding.
    -f, --format <FMT>  'json' for [[[[lat, lng],...],...],...] 'wkt' for a WKT MULTIPOLYGON

$ h3 cellsToMultiPolygon -c 872830828ffffff,87283082effffff
[[[[37.784046, -122.427089], [37.772267, -122.434586], [37.761736, -122.425769], [37.762982, -122.409455], [37.752446, -122.400640], [37.753689, -122.384324], [37.765468, -122.376819], [37.776004, -122.385635], [37.774761, -122.401954], [37.785293, -122.410771]]]]

destroyLinkedMultiPolygon

Free all allocated memory for a linked geo structure. The caller is responsible for freeing memory allocated to the input polygon struct.

C

void destroyLinkedMultiPolygon(LinkedGeoPolygon *polygon);

Java

note

This function exists for memory management and is not exposed.

JavaScript (Live)

note

This function exists for memory management and is not exposed.

Python

note

This function exists for memory management and is not exposed.

Shell

note

This function exists for memory management and is not exposed.