Grid traversal functions - H3

import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';

Grid traversal allows finding cells in the vicinity of an origin cell, and determining how to traverse the grid from one cell to another.

gridDistance

Provides the grid distance between two cells, which is defined as the minimum number of "hops" needed across adjacent cells to get from one cell to the other.

Note that finding the grid distance may fail for a few reasons:

the cells are not comparable (different resolutions),
the cells are too far apart, or
the cells are separated by pentagonal distortion.

This is the same set of limitations as the local IJ coordinate space functions.

H3Error gridDistance(H3Index origin, H3Index h3, int64_t *distance);

Returns 0 (E_SUCCESS) on success, or an error if finding the distance failed.

</TabItem> <TabItem value="java">

java

long gridDistance(long a, long b) throws DistanceUndefinedException;
long gridDistance(String a, String b) throws DistanceUndefinedException;

</TabItem> <TabItem value="javascript">

h3.gridDistance(a, b)

function example() {
  const start = '85283473fffffff';
  const end = '8528342bfffffff';
  return h3.gridDistance(start, end);
}

</TabItem> <TabItem value="python">

h3.grid_distance(h1, h2)

</TabItem> <TabItem value="go">

cell.GridDistance(other)

</TabItem> <TabItem value="duckdb">

sql

h3_grid_distance(h1, h2)

</TabItem> <TabItem value="shell">

$ h3 gridDistance --help
h3: Returns the number of steps along the grid to move from the origin cell to the destination cell
H3 4.1.0

  gridDistance  Returns the number of steps along the grid to move from the origin cell to the destination cell
  -h, --help  Show this help message.
  -o, --origin <cell> Required. The origin H3 cell
  -d, --destination <cell>  Required. The destination H3 cell

bash

$ h3 gridDistance -o 85283473fffffff -d 8528342bfffffff
2

</TabItem> </Tabs>

gridRing

Produces the "hollow ring" of cells which are exactly grid distance k from the origin cell.

If pentagon distortion is encountered, this function will use a more memory-intensive approach than gridRingUnsafe in order to compute the ring.

H3Error gridRing(H3Index origin, int k, H3Index* out);

The caller should allocate memory for the maximum size of the ring, which is given by maxGridRingSize. If fewer than the maximum number of cells are generated, elements in out may be left zero.

Returns 0 (E_SUCCESS) on success.

</TabItem> <TabItem value="java">

java

List<Long> gridRing(long h3, int k);
List<String> gridRing(String h3Address, int k);

</TabItem> <TabItem value="javascript">

h3.gridRing(h3Index, k)

function example() {
  const h = '85283473fffffff';
  const k = 1;
  return h3.gridRing(h, k);
}

</TabItem> <TabItem value="python">

h3.grid_ring(h, k)

</TabItem> <TabItem value="go">

cell.GridRing(k)

</TabItem> <TabItem value="duckdb">

sql

h3_grid_ring(h, k)

</TabItem> <TabItem value="shell">

$ h3 gridRing --help
h3: Returns an array of H3 cells, each cell 'k' steps away from the origin cell
H3 4.1.0

  gridRing  Returns an array of H3 cells, each cell 'k' steps away from the origin cell
  -h, --help  Show this help message.
  -c, --cell <index>  Required. H3 Cell
  -k <distance> Required. Maximum grid distance for the output set
  -f, --format <FMT>  'json' for ["CELL", ...], 'newline' for CELL\n... (Default: json)

bash

$ h3 gridRing -k 1 -c 85283473fffffff
[ "8528340bfffffff", "85283447fffffff", "8528347bfffffff", "85283463fffffff", "85283477fffffff", "8528340ffffffff" ]

</TabItem> </Tabs>

gridRingUnsafe

Produces the "hollow ring" of cells which are exactly grid distance k from the origin cell.

This function may fail if pentagonal distortion is encountered.

H3Error gridRingUnsafe(H3Index origin, int k, H3Index* out);

The caller should allocate memory for the maximum size of the ring, which is given by maxGridRingSize.

Returns 0 (E_SUCCESS) if no pentagonal distortion was encountered.

</TabItem> <TabItem value="java">

java

List<Long> gridRingUnsafe(long h3, int k) throws PentagonEncounteredException;
List<String> gridRingUnsafe(String h3Address, int k) throws PentagonEncounteredException;

</TabItem> <TabItem value="javascript">

h3.gridRingUnsafe(h3Index, k)

function example() {
  const h = '85283473fffffff';
  const k = 1;
  return h3.gridRingUnsafe(h, k);
}

</TabItem> <TabItem value="python">

:::note

This function is not exposed.

:::

</TabItem> <TabItem value="go">

cell.GridRingUnsafe(k)

</TabItem> <TabItem value="duckdb">

sql

h3_grid_ring_unsafe(h, k)

</TabItem> <TabItem value="shell">

:::note

This function is not exposed.

:::

</TabItem> </Tabs>

maxGridRingSize

This function provides the maximum number of cells in the grid that are exactly grid distance k away from an origin, which is 6*k if k > 0 and 1 if k == 0.

H3Error maxGridRingSize(int k, int64_t* out);

Returns 0 (E_SUCCESS) if no pentagonal distortion was encountered.

</TabItem> <TabItem value="java">

:::note

This function exists for memory management and is not exposed.

:::

</TabItem> <TabItem value="javascript">

:::note

This function exists for memory management and is not exposed.

:::

</TabItem> <TabItem value="python">

:::note

This function exists for memory management and is not exposed.

:::

</TabItem> <TabItem value="go">

:::note

This function exists for memory management and is not exposed.

:::

</TabItem> <TabItem value="duckdb">

:::note

This function exists for memory management and is not exposed.

:::

</TabItem> <TabItem value="shell">

:::note

This function exists for memory management and is not exposed.

:::

</TabItem> </Tabs>

gridDisk

Produces the "filled-in disk" of cells which are at most grid distance k from the origin cell.

Output order is not guaranteed.

H3Error gridDisk(H3Index origin, int k, H3Index* out);

Elements of the output array may be left as zero, which can happen when crossing a pentagon.

Returns 0 (E_SUCCESS) on success.

</TabItem> <TabItem value="java">

java

List<Long> gridDisk(long origin, int k);
List<String> gridDisk(String origin, int k);

</TabItem> <TabItem value="javascript">

h3.gridDisk(origin, k)

function example() {
  const h = '85283473fffffff';
  const k = 5;
  return h3.gridDisk(h, k);
}

</TabItem> <TabItem value="python">

h3.grid_disk(origin, k)

</TabItem> <TabItem value="go">

cell.GridDisk(k)

</TabItem> <TabItem value="duckdb">

sql

h3_grid_disk(origin, k)

</TabItem> <TabItem value="shell">

$ h3 gridDisk --help
h3: Returns an array of a H3 cells within 'k' steps of the origin cell
H3 4.1.0

	gridDisk	Returns an array of a H3 cells within 'k' steps of the origin cell
	-h, --help	Show this help message.
	-c, --cell <index>	Required. H3 Cell
	-k <distance>	Required. Maximum grid distance for the output set
	-f, --format <FMT>	'json' for ["CELL", ...], 'newline' for CELL\n... (Default: json)

bash

$ h3 gridDisk -k 5 -c 85283473fffffff
[ "85283473fffffff", "85283447fffffff", "8528347bfffffff", "85283463fffffff", "85283477fffffff", "8528340ffffffff", "8528340bfffffff", "85283457fffffff", "85283443fffffff", "8528344ffffffff", "852836b7fffffff", "8528346bfffffff", "8528346ffffffff", "85283467fffffff", "8528342bfffffff", "8528343bfffffff", "85283407fffffff", "85283403fffffff", "8528341bfffffff", "852834cffffffff", "85283453fffffff", "8528345bfffffff", "8528344bfffffff", "852836b3fffffff", "852836a3fffffff", "852836a7fffffff", "852830d3fffffff", "852830d7fffffff", "8528309bfffffff", "85283093fffffff", "8528342ffffffff", "85283423fffffff", "85283433fffffff", "852834abfffffff", "85283417fffffff", "85283413fffffff", "852834c7fffffff", "852834c3fffffff", "852834cbfffffff", "8529a927fffffff", "8529a92ffffffff", "85283697fffffff", "85283687fffffff", "852836bbfffffff", "852836abfffffff", "852836affffffff", "852830dbfffffff", "852830c3fffffff", "852830c7fffffff", "8528308bfffffff", "85283083fffffff", "85283097fffffff", "8528355bfffffff", "85283427fffffff", "85283437fffffff", "852834affffffff", "852834a3fffffff", "852834bbfffffff", "8528348ffffffff", "8528348bfffffff", "852834d7fffffff", "852834d3fffffff", "852834dbfffffff", "8529a937fffffff", "8529a923fffffff", "8529a92bfffffff", "85283693fffffff", "85283683fffffff", "8528368ffffffff", "85283617fffffff", "85283607fffffff", "85283633fffffff", "85283637fffffff", "852830cbfffffff", "852830cffffffff", "8528301bfffffff", "85283013fffffff", "8528308ffffffff", "85283087fffffff", "8528354bfffffff", "85283543fffffff", "85283553fffffff", "852835cbfffffff", "852835dbfffffff", "852834a7fffffff", "852834b7fffffff", "852834b3fffffff", "85283487fffffff", "85283483fffffff", "8528349bfffffff", "85291a6ffffffff" ]

</TabItem> </Tabs>

maxGridDiskSize

Maximum number of cells that can result from the gridDisk function for a given k.

H3Error maxGridDiskSize(int k, int64_t *out);

Returns 0 (E_SUCCESS) on success.

</TabItem> <TabItem value="java">

:::note

This function exists for memory management and is not exposed.

:::

</TabItem> <TabItem value="javascript">

:::note

This function exists for memory management and is not exposed.

:::

</TabItem> <TabItem value="python">

:::note

This function exists for memory management and is not exposed.

:::

</TabItem> <TabItem value="go">

:::note

This function exists for memory management and is not exposed.

:::

</TabItem> <TabItem value="duckdb">

:::note

This function exists for memory management and is not exposed.

:::

</TabItem> <TabItem value="shell">

:::note

This function exists for memory management and is not exposed.

:::

</TabItem> </Tabs>

gridDiskDistances

Produces the same set of cells as gridDisk, but along with each cell's grid distance from the origin cell.

Output order is not guaranteed.

H3Error gridDiskDistances(H3Index origin, int k, H3Index* out, int* distances);

Elements of the output array may be left as zero, which can happen when crossing a pentagon.

Returns 0 (E_SUCCESS) on success.

</TabItem> <TabItem value="java">

java

List<List<Long>> gridDiskDistances(long origin, int k);
List<List<String>> gridDiskDistances(String origin, int k);

</TabItem> <TabItem value="javascript">

h3.gridDiskDistances(origin, k)

function example() {
  const h = '85283473fffffff';
  const k = 5;
  return h3.gridDiskDistances(h, k);
}

</TabItem> <TabItem value="python">

:::note

This function is not exposed in Python.

:::

</TabItem> <TabItem value="go">

cell.GridDiskDistances(k)

</TabItem> <TabItem value="duckdb">

sql

h3_grid_disk_distances(origin, k)

</TabItem> <TabItem value="shell">

$ h3 gridDiskDistances --help
h3: Returns an array of arrays of H3 cells, each array containing cells 'k' steps away from the origin cell, based on the outer array index
H3 4.1.0

	gridDiskDistances	Returns an array of arrays of H3 cells, each array containing cells 'k' steps away from the origin cell, based on the outer array index
	-h, --help	Show this help message.
	-c, --cell <index>	Required. H3 Cell
	-k <distance>	Required. Maximum grid distance for the output set
	-f, --format <FMT>	'json' for [["CELL", ...], ...], 'newline' for CELL\n with an extra newline between rings (Default: json)

bash

$ h3 gridDiskDistances -k 5 -c 85283473fffffff
[["85283473fffffff"], ["85283447fffffff", "8528347bfffffff", "85283463fffffff", "85283477fffffff", "8528340ffffffff", "8528340bfffffff"], ["85283457fffffff", "85283443fffffff", "8528344ffffffff", "852836b7fffffff", "8528346bfffffff", "8528346ffffffff", "85283467fffffff", "8528342bfffffff", "8528343bfffffff", "85283407fffffff", "85283403fffffff", "8528341bfffffff"], ["852834cffffffff", "85283453fffffff", "8528345bfffffff", "8528344bfffffff", "852836b3fffffff", "852836a3fffffff", "852836a7fffffff", "852830d3fffffff", "852830d7fffffff", "8528309bfffffff", "85283093fffffff", "8528342ffffffff", "85283423fffffff", "85283433fffffff", "852834abfffffff", "85283417fffffff", "85283413fffffff", "852834c7fffffff"], ["852834c3fffffff", "852834cbfffffff", "8529a927fffffff", "8529a92ffffffff", "85283697fffffff", "85283687fffffff", "852836bbfffffff", "852836abfffffff", "852836affffffff", "852830dbfffffff", "852830c3fffffff", "852830c7fffffff", "8528308bfffffff", "85283083fffffff", "85283097fffffff", "8528355bfffffff", "85283427fffffff", "85283437fffffff", "852834affffffff", "852834a3fffffff", "852834bbfffffff", "8528348ffffffff", "8528348bfffffff", "852834d7fffffff"], ["852834d3fffffff", "852834dbfffffff", "8529a937fffffff", "8529a923fffffff", "8529a92bfffffff", "85283693fffffff", "85283683fffffff", "8528368ffffffff", "85283617fffffff", "85283607fffffff", "85283633fffffff", "85283637fffffff", "852830cbfffffff", "852830cffffffff", "8528301bfffffff", "85283013fffffff", "8528308ffffffff", "85283087fffffff", "8528354bfffffff", "85283543fffffff", "85283553fffffff", "852835cbfffffff", "852835dbfffffff", "852834a7fffffff", "852834b7fffffff", "852834b3fffffff", "85283487fffffff", "85283483fffffff", "8528349bfffffff", "85291a6ffffffff"]]

</TabItem> </Tabs>

gridDiskUnsafe

Produces cells within grid distance k of the origin cell, just like gridDisk. However, the function may return an error code if pentagonal distorition is encountered. In this case, the output in the out array is undefined.

Users can fall back to calling the slower but more robust gridDiskDistances.

H3Error gridDiskUnsafe(H3Index origin, int k, H3Index* out);

Output is placed in the provided array in order of increasing distance from the origin. The provided array must be of size maxGridDiskSize(k).

Returns 0 (E_SUCCESS) if no pentagonal distortion is encountered.

</TabItem> <TabItem value="java">

java

List<List<Long>> gridDiskUnsafe(Long h3, int k) throws PentagonEncounteredException;
List<List<String>> gridDiskUnsafe(String h3Address, int k) throws PentagonEncounteredException;

</TabItem> <TabItem value="javascript">

:::note

This function is not exposed.

:::

</TabItem> <TabItem value="python">

:::note

This function is not exposed.

:::

</TabItem> <TabItem value="go">

:::note

This function is not exposed.

:::

</TabItem> <TabItem value="duckdb">

sql

h3_grid_disk_unsafe(origin, k)

</TabItem> <TabItem value="shell">

:::note

This function is not exposed.

:::

</TabItem> </Tabs>

gridDiskDistancesUnsafe

gridDiskDistancesUnsafe produces indexes within k distance of the origin index. Output behavior is undefined when one of the indexes returned by this function is a pentagon or is in the pentagon distortion area.

Output is placed in the provided array in order of increasing distance from the origin. The distances in hexagons is placed in the distances array at the same offset. The provided array must be of size maxGridDiskSize(k).

H3Error gridDiskDistancesUnsafe(H3Index origin, int k, H3Index* out, int* distances);

Returns 0 (E_SUCCESS) if no pentagonal distortion is encountered.

</TabItem> <TabItem value="java">

:::note

This function is not exposed because the same functionality is exposed by gridDiskUnsafe

:::

</TabItem> <TabItem value="javascript">

:::note

This function is not exposed.

:::

</TabItem> <TabItem value="python">

:::note

This function is not exposed.

:::

</TabItem> <TabItem value="go">

:::note

This function is not exposed.

:::

</TabItem> <TabItem value="duckdb">

sql

h3_grid_disk_distances_unsafe(origin, k)

</TabItem> <TabItem value="shell">

:::note

This function is not exposed.

:::

</TabItem> </Tabs>

gridDiskDistancesSafe

gridDiskDistancesSafe produces indexes within k distance of the origin index.

H3Error gridDiskDistancesSafe(H3Index origin, int k, H3Index* out, int* distances);

Returns 0 (E_SUCCESS) on success.

</TabItem> <TabItem value="java">

:::note

This function is not exposed because the same functionality is exposed by gridDiskSafe

:::

</TabItem> <TabItem value="javascript">

:::note

This function is not exposed.

:::

</TabItem> <TabItem value="python">

:::note

This function is not exposed.

:::

</TabItem> <TabItem value="go">

:::note

This function is not exposed.

:::

</TabItem> <TabItem value="duckdb">

sql

h3_grid_disk_distances_safe(origin, k)

</TabItem> <TabItem value="shell">

:::note

This function is not exposed.

:::

</TabItem> </Tabs>

gridDisksUnsafe

gridDisksUnsafe takes an array of input cells and a max k and returns an array of cells sorted first by the original cell indices and then by the grid ring (0 to max), with no guaranteed sorting within each grid ring group.

H3Error gridDisksUnsafe(H3Index* h3Set, int length, int k, H3Index* out);

Returns 0 (E_SUCCESS) if no pentagonal distortion was encountered.

</TabItem> <TabItem value="java">

:::note

This function is not exposed because the same functionality is exposed by gridDiskUnsafe

:::

</TabItem> <TabItem value="javascript">

:::note

This function is not exposed.

:::

</TabItem> <TabItem value="python">

:::note

This function is not exposed.

:::

</TabItem> <TabItem value="go">

:::note

This function is not exposed.

:::

</TabItem> <TabItem value="duckdb">

:::note

This function is not exposed.

:::

</TabItem> <TabItem value="shell">

:::note

This function is not exposed.

:::

</TabItem> </Tabs>

gridPathCells

Given two H3 cells, return a minimal-length contiguous path of cells between them (inclusive of the endpoint cells).

This function may fail if the cells are very far apart, or if the cells are on opposite sides of a pentagon.

Notes:

The output of this function should not be considered stable across library versions. The only guarantees are that the path length will be gridDistance(start, end) + 1 and that every cell in the path will be a neighbor of the preceding cell.
Paths exist in the H3 grid of cells, and may not align closely with either Cartesian lines or great arcs.

H3Error gridPathCells(H3Index start, H3Index end, H3Index* out);

Returns 0 (E_SUCCESS) if no pentagonal distortion was encountered.

</TabItem> <TabItem value="java">

java

List<Long> gridPathCells(long start, long end) throws LineUndefinedException
List<String> gridPathCells(String startAddress, String endAddress) throws LineUndefinedException

</TabItem> <TabItem value="javascript">

h3.gridPathCells(start, end)

function example() {
  const start = '85283473fffffff';
  const end = '8528342bfffffff';
  return h3.gridPathCells(start, end);
}

</TabItem> <TabItem value="python">

h3.grid_path_cells(start, end)

</TabItem> <TabItem value="go">

cell.GridPath(other)

</TabItem> <TabItem value="duckdb">

sql

h3_grid_path_cells(start, end)

</TabItem> <TabItem value="shell">

$ h3 gridPathCells --help
h3: Returns an array of H3 cells from the origin cell to the destination cell (inclusive)
H3 4.1.0

	gridPathCells	Returns an array of H3 cells from the origin cell to the destination cell (inclusive)
	-h, --help	Show this help message.
	-o, --origin <cell>	Required. The origin H3 cell
	-d, --destination <cell>	Required. The destination H3 cell
	-f, --format <FMT>	'json' for ["CELL", ...], 'newline' for CELL\n... (Default: json)

bash

$ h3 gridPathCells -o 85283473fffffff -d 8528342bfffffff
[ "85283473fffffff", "85283477fffffff", "8528342bfffffff" ]

</TabItem> </Tabs>

gridPathCellsSize

Number of cells in a grid path from the start cell to the end cell, to be used for allocating memory.

H3Error gridPathCellsSize(H3Index start, H3Index end, int64_t* size);

Returns 0 (E_SUCCESS) on success, or an error if the path cannot be computed.

</TabItem> <TabItem value="java">

:::note

This function exists for memory management and is not exposed.

:::

</TabItem> <TabItem value="javascript">

:::note

This function exists for memory management and is not exposed.

:::

</TabItem> <TabItem value="python">

:::note

This function exists for memory management and is not exposed.

:::

</TabItem> <TabItem value="go">

:::note

This function exists for memory management and is not exposed.

:::

</TabItem> <TabItem value="duckdb">

:::note

This function exists for memory management and is not exposed.

:::

</TabItem> <TabItem value="shell">

:::note

This function exists for memory management and is not exposed.

:::

</TabItem> </Tabs>

cellToLocalIj

Produces local IJ coordinates for an H3 cell anchored by an origin.

mode is reserved for future expansion and must be set to 0.

This function's output is not guaranteed to be compatible across different versions of H3.

H3Error cellToLocalIj(H3Index origin, H3Index h3, uint32_t mode, CoordIJ *out);

Returns 0 (E_SUCCESS) on success.

</TabItem> <TabItem value="java">

java

CoordIJ cellToLocalIj(long origin, long h3) throws PentagonEncounteredException, LocalIjUndefinedException;
CoordIJ cellToLocalIj(String originAddress, String h3Address) throws PentagonEncounteredException, LocalIjUndefinedException;

</TabItem> <TabItem value="javascript">

h3.cellToLocalIj(origin, h3)

function example() {
  const origin = '85283473fffffff';
  const h = '8528342bfffffff';
  const {i, j} = h3.cellToLocalIj(origin, h);
  return [i, j];
}

</TabItem> <TabItem value="python">

h3.cell_to_local_ij(origin, h)

</TabItem> <TabItem value="go">

h3.CellToLocalIJ(origin, h)

</TabItem> <TabItem value="duckdb">

sql

h3_cell_to_local_ij(origin, h)

</TabItem> <TabItem value="shell">

$ h3 cellToLocalIj --help
h3: Returns the IJ coordinate for a cell anchored to an origin cell
H3 4.1.0

	cellToLocalIj	Returns the IJ coordinate for a cell anchored to an origin cell
	-h, --help	Show this help message.
	-c, --cell <index>	Required. H3 Cell
	-o, --origin <cell>	Required. The origin H3 cell
	-f, --format <FMT>	'json' for [I, J], 'newline' for I\nJ\n (Default: json)

bash

$ h3 cellToLocalIj -o 85283473fffffff -c 8528342bfffffff
[25, 13]

</TabItem> </Tabs>

localIjToCell

Produces an H3 cell from local IJ coordinates anchored by an origin.

mode is reserved for future expansion and must be set to 0.

This function's output is not guaranteed to be compatible across different versions of H3.

H3Error localIjToCell(H3Index origin, const CoordIJ *ij, uint32_t mode, H3Index *out);

Returns 0 (E_SUCCESS) on success.

</TabItem> <TabItem value="java">

java

long localIjToCell(long origin, CoordIJ ij) throws LocalIjUndefinedException;
String localIjToCell(String originAddress, CoordIJ ij) throws LocalIjUndefinedException;

</TabItem> <TabItem value="javascript">

h3.localIjToCell(origin, coords)

function example() {
  const h = '85283473fffffff';
  const coords = {i: 0, j: 0};
  return h3.localIjToCell(h, coords);
}

</TabItem> <TabItem value="python">

h3.local_ij_to_cell(origin, i, j)

</TabItem> <TabItem value="go">

h3.LocalIJToCell(origin, CoordIJ{i, j})

</TabItem> <TabItem value="duckdb">

sql

h3_local_ij_to_cell(origin, i, j)

</TabItem> <TabItem value="shell">

$ h3 localIjToCell --help
h3: Returns the H3 index from a local IJ coordinate anchored to an origin cell
H3 4.1.0

	localIjToCell	Returns the H3 index from a local IJ coordinate anchored to an origin cell
	-h, --help	Show this help message.
	-o, --origin <cell>	Required. The origin H3 cell
	-i <i>	Required. The I dimension of the IJ coordinate
	-j <j>	Required. The J dimension of the IJ coordinate
	-f, --format <FMT>	'json' for "CELL"\n, 'newline' for CELL\n (Default: json)

bash

$ h3 localIjToCell -o 85283473fffffff -i 0 -j 0
"85280003fffffff"

</TabItem> </Tabs>