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

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.