---
id: traversal
title: Grid traversal functions
sidebar_label: Traversal
slug: /api/traversal
---

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.

<Tabs
  groupId="language"
  defaultValue="c"
  values={[
    {label: 'C', value: 'c'},
    {label: 'Java', value: 'java'},
    {label: 'JavaScript (Live)', value: 'javascript'},
    {label: 'Python', value: 'python'},
    {label: 'Go', value: 'go'},
    {label: 'DuckDB', value: 'duckdb'},
    {label: 'Shell', value: 'shell'},
  ]
}>
<TabItem value="c">

```c
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">

```js
h3.gridDistance(a, b)
```

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

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

```py
h3.grid_distance(h1, h2)
```

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

```go
cell.GridDistance(other)
```

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

```sql
h3_grid_distance(h1, h2)
```

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

```sh
$ 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.

<Tabs
  groupId="language"
  defaultValue="c"
  values={[
    {label: 'C', value: 'c'},
    {label: 'Java', value: 'java'},
    {label: 'JavaScript (Live)', value: 'javascript'},
    {label: 'Python', value: 'python'},
    {label: 'Go', value: 'go'},
    {label: 'DuckDB', value: 'duckdb'},
    {label: 'Shell', value: 'shell'},
  ]
}>
<TabItem value="c">

```c
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">

```js
h3.gridRing(h3Index, k)
```

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

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

```py
h3.grid_ring(h, k)
```

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

```go
cell.GridRing(k)
```

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

```sql
h3_grid_ring(h, k)
```

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

```sh
$ 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.

<Tabs
  groupId="language"
  defaultValue="c"
  values={[
    {label: 'C', value: 'c'},
    {label: 'Java', value: 'java'},
    {label: 'JavaScript (Live)', value: 'javascript'},
    {label: 'Python', value: 'python'},
    {label: 'Go', value: 'go'},
    {label: 'DuckDB', value: 'duckdb'},
    {label: 'Shell', value: 'shell'},
  ]
}>
<TabItem value="c">

```c
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">

```js
h3.gridRingUnsafe(h3Index, k)
```

```js live
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">

```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`.

<Tabs
  groupId="language"
  defaultValue="c"
  values={[
    {label: 'C', value: 'c'},
    {label: 'Java', value: 'java'},
    {label: 'JavaScript (Live)', value: 'javascript'},
    {label: 'Python', value: 'python'},
    {label: 'Go', value: 'go'},
    {label: 'DuckDB', value: 'duckdb'},
    {label: 'Shell', value: 'shell'},
  ]
}>
<TabItem value="c">

```c
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.

<Tabs
  groupId="language"
  defaultValue="c"
  values={[
    {label: 'C', value: 'c'},
    {label: 'Java', value: 'java'},
    {label: 'JavaScript (Live)', value: 'javascript'},
    {label: 'Python', value: 'python'},
    {label: 'Go', value: 'go'},
    {label: 'DuckDB', value: 'duckdb'},
    {label: 'Shell', value: 'shell'},
  ]
}>
<TabItem value="c">

```c
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">

```js
h3.gridDisk(origin, k)
```

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

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

```py
h3.grid_disk(origin, k)
```

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

```go
cell.GridDisk(k)
```

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

```sql
h3_grid_disk(origin, k)
```

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

```sh
$ 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`.

<Tabs
  groupId="language"
  defaultValue="c"
  values={[
    {label: 'C', value: 'c'},
    {label: 'Java', value: 'java'},
    {label: 'JavaScript (Live)', value: 'javascript'},
    {label: 'Python', value: 'python'},
    {label: 'Go', value: 'go'},
    {label: 'DuckDB', value: 'duckdb'},
    {label: 'Shell', value: 'shell'},
  ]
}>
<TabItem value="c">

```c
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.

<Tabs
  groupId="language"
  defaultValue="c"
  values={[
    {label: 'C', value: 'c'},
    {label: 'Java', value: 'java'},
    {label: 'JavaScript (Live)', value: 'javascript'},
    {label: 'Python', value: 'python'},
    {label: 'Go', value: 'go'},
    {label: 'DuckDB', value: 'duckdb'},
    {label: 'Shell', value: 'shell'},
  ]
}>
<TabItem value="c">

```c
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">

```js
h3.gridDiskDistances(origin, k)
```

```js live
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">

```go
cell.GridDiskDistances(k)
```

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

```sql
h3_grid_disk_distances(origin, k)
```

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

```sh
$ 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`.

<Tabs
  groupId="language"
  defaultValue="c"
  values={[
    {label: 'C', value: 'c'},
    {label: 'Java', value: 'java'},
    {label: 'JavaScript (Live)', value: 'javascript'},
    {label: 'Python', value: 'python'},
    {label: 'Go', value: 'go'},
    {label: 'DuckDB', value: 'duckdb'},
    {label: 'Shell', value: 'shell'},
  ]
}>
<TabItem value="c">

```c
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)`.

<Tabs
  groupId="language"
  defaultValue="c"
  values={[
    {label: 'C', value: 'c'},
    {label: 'Java', value: 'java'},
    {label: 'JavaScript (Live)', value: 'javascript'},
    {label: 'Python', value: 'python'},
    {label: 'Go', value: 'go'},
    {label: 'DuckDB', value: 'duckdb'},
    {label: 'Shell', value: 'shell'},
  ]
}>
<TabItem value="c">

```c
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.

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)`.

<Tabs
  groupId="language"
  defaultValue="c"
  values={[
    {label: 'C', value: 'c'},
    {label: 'Java', value: 'java'},
    {label: 'JavaScript (Live)', value: 'javascript'},
    {label: 'Python', value: 'python'},
    {label: 'Go', value: 'go'},
    {label: 'DuckDB', value: 'duckdb'},
    {label: 'Shell', value: 'shell'},
  ]
}>
<TabItem value="c">

```c
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.

<Tabs
  groupId="language"
  defaultValue="c"
  values={[
    {label: 'C', value: 'c'},
    {label: 'Java', value: 'java'},
    {label: 'JavaScript (Live)', value: 'javascript'},
    {label: 'Python', value: 'python'},
    {label: 'Go', value: 'go'},
    {label: 'DuckDB', value: 'duckdb'},
    {label: 'Shell', value: 'shell'},
  ]
}>
<TabItem value="c">

```c
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.

<Tabs
  groupId="language"
  defaultValue="c"
  values={[
    {label: 'C', value: 'c'},
    {label: 'Java', value: 'java'},
    {label: 'JavaScript (Live)', value: 'javascript'},
    {label: 'Python', value: 'python'},
    {label: 'Go', value: 'go'},
    {label: 'DuckDB', value: 'duckdb'},
    {label: 'Shell', value: 'shell'},
  ]
}>
<TabItem value="c">

```c
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">

```js
h3.gridPathCells(start, end)
```

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

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

```py
h3.grid_path_cells(start, end)
```

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

```go
cell.GridPath(other)
```

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

```sql
h3_grid_path_cells(start, end)
```

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

```sh
$ 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.

<Tabs
  groupId="language"
  defaultValue="c"
  values={[
    {label: 'C', value: 'c'},
    {label: 'Java', value: 'java'},
    {label: 'JavaScript (Live)', value: 'javascript'},
    {label: 'Python', value: 'python'},
    {label: 'Go', value: 'go'},
    {label: 'DuckDB', value: 'duckdb'},
    {label: 'Shell', value: 'shell'},
  ]
}>
<TabItem value="c">

```c
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.

<Tabs
  groupId="language"
  defaultValue="c"
  values={[
    {label: 'C', value: 'c'},
    {label: 'Java', value: 'java'},
    {label: 'JavaScript (Live)', value: 'javascript'},
    {label: 'Python', value: 'python'},
    {label: 'Go', value: 'go'},
    {label: 'DuckDB', value: 'duckdb'},
    {label: 'Shell', value: 'shell'},
  ]
}>
<TabItem value="c">

```c
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">

```js
h3.cellToLocalIj(origin, h3)
```

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

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

```py
h3.cell_to_local_ij(origin, h)
```

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

```go
h3.CellToLocalIJ(origin, h)
```

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

```sql
h3_cell_to_local_ij(origin, h)
```

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

```sh
$ 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.

<Tabs
  groupId="language"
  defaultValue="c"
  values={[
    {label: 'C', value: 'c'},
    {label: 'Java', value: 'java'},
    {label: 'JavaScript (Live)', value: 'javascript'},
    {label: 'Python', value: 'python'},
    {label: 'Go', value: 'go'},
    {label: 'DuckDB', value: 'duckdb'},
    {label: 'Shell', value: 'shell'},
  ]
}>
<TabItem value="c">

```c
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">

```js
h3.localIjToCell(origin, coords)
```

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

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

```py
h3.local_ij_to_cell(origin, i, j)
```

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

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

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

```sql
h3_local_ij_to_cell(origin, i, j)
```

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

```sh
$ 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>


