---
id: hierarchy
title: Hierarchical grid functions
sidebar_label: Hierarchy
slug: /api/hierarchy
---

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

These functions permit moving between resolutions in the H3 grid system.
The functions produce parent cells (coarser), or child cells (finer).

## cellToParent

Provides the unique ancestor (coarser) cell of the given `cell` for
the provided resolution. If the input cell has resolution `r`, then
`parentRes = r - 1` would give the immediate parent,
`parentRes = r - 2` would give the grandparent, and so on.

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

```c
H3Error cellToParent(H3Index cell, int parentRes, H3Index *parent);
```

Returns 0 (`E_SUCCESS`) on success.

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

```java
long cellToParent(long cell, int parentRes);
String cellToParentAddress(String cellAddress, int parentRes);
```

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

```js
h3.cellToParent(cell, parentRes)
```

```js live
function example() {
  const cell = '85283473fffffff';
  return h3.cellToParent(cell, 4);
}
```

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

```py
h3.cell_to_parent(h, res=None)
```

If `res = None`, we set `res = resolution(h) - 1`.
See the [h3-py docs](https://uber.github.io/h3-py/api_verbose.html#h3.cell_to_parent).

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

```sh
$ h3 cellToParent --help
h3: Returns the H3 index that is the parent (or higher) of the provided cell
H3 4.1.0

	cellToParent	Returns the H3 index that is the parent (or higher) of the provided cell
	-h, --help	Show this help message.
	-c, --cell <index>	Required. H3 Cell
	-r, --resolution <res>	Required. Resolution, 0-14 inclusive, excluding 15 as it can never be a parent
	-f, --format <FMT>	'json' for "CELL"\n, 'newline' for CELL\n (Default: json)
```

```bash
$ h3 cellToParent -c 85283473fffffff -r 4
"8428347ffffffff"
```

</TabItem>
</Tabs>


## cellToChildren

Provides the children (descendant) cells of `cell` at
resolution `childRes`.

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

```c
H3Error cellToChildren(H3Index cell, int childRes, H3Index *children);
```

`children` must be an array of at least size `cellToChildrenSize(cell, childRes)`.

Returns 0 (`E_SUCCESS`) on success.

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

```java
List<Long> cellToChildren(long cell, int childRes);
List<String> cellToChildren(String cellAddress, int childRes);
```

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

```js
h3.cellToChildren(cell, childRes)
```

```js live
function example() {
  const cell = '85283473fffffff';
  return h3.cellToChildren(cell, 6);
}
```

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

```py
h3.cell_to_children(h, res=None)
```

If `res = None`, we set `res = resolution(h) + 1`.
See the [h3-py docs](https://uber.github.io/h3-py/api_verbose.html#h3.cell_to_children).

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

```sh
$ h3 cellToChildren --help
h3: Returns an array of H3 indexes that are the children (or lower) of the provided cell
H3 4.1.0

	cellToChildren	Returns an array of H3 indexes that are the children (or lower) of the provided cell
	-h, --help	Show this help message.
	-c, --cell <index>	Required. H3 Cell
	-r, --resolution <res>	Required. Resolution, 1-15 inclusive, excluding 0 as it can never be a child
	-f, --format <FMT>	'json' for ["CELL", ...], 'newline' for CELL\n... (Default: json)
```

```bash
$ h3 cellToChildren -c 85283473fffffff -r 6
[ "862834707ffffff", "86283470fffffff", "862834717ffffff", "86283471fffffff", "862834727ffffff", "86283472fffffff", "862834737ffffff" ]
```

</TabItem>
</Tabs>


## cellToChildrenSize

Provides the number of children at a given resolution of the given cell.

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

```c
H3Error cellToChildrenSize(H3Index cell, int childRes, int64_t *out);
```

Provides the size of the `children` array needed for the given inputs to `cellToChildren`.

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


```py
h3.cell_to_children_size(h, res=None)
```

If `res = None`, we set `res = resolution(h) + 1`.
See the [h3-py docs](https://uber.github.io/h3-py/api_verbose.html#h3.cell_to_children_size).


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

```sh
$ h3 cellToChildrenSize --help
h3: Returns the maximum number of children for a given cell at the specified child resolution
H3 4.1.0

	cellToChildrenSize	Returns the maximum number of children for a given cell at the specified child resolution
	-h, --help	Show this help message.
	-c, --cell <index>	Required. H3 Cell
	-r, --resolution <res>	Required. Resolution, 1-15 inclusive, excluding 0 as it can never be a child
```

```bash
$ h3 cellToChildrenSize -c 85283473fffffff -r 6
7
```

</TabItem>
</Tabs>


## cellToCenterChild

Provides the center child (finer) cell contained by `cell` at resolution `childRes`.

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

```c
H3Error cellToCenterChild(H3Index cell, int childRes, H3Index *child);
```

Returns 0 (`E_SUCCESS`) on success.


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

```java
long cellToCenterChild(long cell, int childRes);
String cellToCenterChild(String cellAddress, int childRes);
```

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

```js
h3.cellToCenterChild(cell, childRes)
```

```js live
function example() {
  const cell = '85283473fffffff';
  return h3.cellToCenterChild(cell, 7);
}
```

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

```py
h3.cell_to_center_child(h, res=None)
```

If `res = None`, we set `res = resolution(h) + 1`.
See the [h3-py docs](https://uber.github.io/h3-py/api_verbose.html#h3.cell_to_center_child).

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

```sh
$ h3 cellToCenterChild --help
h3: Returns the H3 index that is the centrally-placed child (or lower) of the provided cell
H3 4.1.0

	cellToCenterChild	Returns the H3 index that is the centrally-placed child (or lower) of the provided cell
	-h, --help	Show this help message.
	-c, --cell <index>	Required. H3 Cell
	-r, --resolution <res>	Required. Resolution, 1-15 inclusive, excluding 0 as it can never be a child
	-f, --format <FMT>	'json' for "CELL"\n, 'newline' for CELL\n (Default: json)
```

```bash
$ h3 cellToCenterChild -c 85283473fffffff -r 7
"872834700ffffff"
```

</TabItem>
</Tabs>


## cellToChildPos

Provides the position of the child cell within an ordered list of all children of the cell's parent at the specified resolution `parentRes`.
The order of the ordered list is the same as that returned by `cellToChildren`.
This is the complement of `childPosToCell`.

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

```c
H3Error cellToChildPos(H3Index child, int parentRes, int64_t *out);
```

Returns 0 (`E_SUCCESS`) on success.

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

```java
long cellToChildPos(long child, int parentRes);
long cellToChildPos(String childAddress, int parentRes);
```

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

```js
h3.cellToChildPos(child, parentRes)
```

```js live
function example() {
  const cell = '85283473fffffff';
  return h3.cellToChildPos(cell, 3);
}
```

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

```py
h3.cell_to_child_pos(child, res_parent)
```

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

```sh
$ h3 cellToChildPos --help
h3: Returns the position of the child cell within an ordered list of all children of the cell's parent at the specified child resolution
H3 4.1.0

	cellToChildPos	Returns the position of the child cell within an ordered list of all children of the cell's parent at the specified child resolution
	-h, --help	Show this help message.
	-c, --cell <index>	Required. H3 Cell
	-r, --resolution <res>	Required. Resolution, 1-15 inclusive, excluding 0 as it can never be a child
```

```bash
$ h3 cellToChildPos -c 85283473fffffff -r 3
25
```

</TabItem>
</Tabs>


## childPosToCell

Provides the child cell at a given position within an ordered list of all children of `parent` at the specified resolution `childRes`.
The order of the ordered list is the same as that returned by `cellToChildren`.
This is the complement of `cellToChildPos`.

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

```c
H3Error childPosToCell(int64_t childPos, H3Index parent, int childRes, H3Index *child);
```

Returns 0 (`E_SUCCESS`) on success.


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

```java
long childPosToCell(long childPos, long parent, int childRes);
String childPosToCell(long childPos, String parentAddress, int childRes);
```

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

```js
h3.childPosToCell(childPos, parent, childRes);
```

```js live
function example() {
  const parent = '85283473fffffff';
  const childPos = 42;
  return h3.childPosToCell(childPos, parent, 7);
}
```

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

```py
h3.child_pos_to_cell(parent, res_child, child_pos)
```

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

```sh
$ h3 childPosToCell --help
h3: Returns the child cell at a given position and resolution within an ordered list of all children of the parent cell
H3 4.1.0

	childPosToCell	Returns the child cell at a given position and resolution within an ordered list of all children of the parent cell
	-h, --help	Show this help message.
	-c, --cell <index>	Required. H3 Cell
	-r, --resolution <res>	Required. Resolution, 1-15 inclusive, excluding 0 as it can never be a child
	-p, --position <pos>	Required. The child position within the set of children of the parent cell
	-f, --format <FMT>	'json' for "CELL"\n, 'newline' for CELL\n (Default: json)
```

```bash
$ h3 childPosToCell -p 42 -c 85283473fffffff -r 7
"872834730ffffff"
```

</TabItem>
</Tabs>


## compactCells

Compacts a collection of H3 cells by recursively replacing children cells
with their parents if all children are present.
Input cells must all share the same resolution.

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

```c
H3Error compactCells(const H3Index *cellSet, H3Index *compactedSet, const int64_t numCells);
```

Compacts `cellSet` into the array `compactedSet`.
`compactedSet` must be at least the size of `cellSet` (in case the set cannot be compacted).

Returns 0 (`E_SUCCESS`) on success.

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

```java
List<Long> compactCells(Collection<Long> cells);
List<String> compactCellAddress(Collection<String> cells);
```

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

```js
h3.compactCells(cells)
```

```js live
function example() {
  const cell = '85283473fffffff';
  const nearby = h3.gridDisk(cell, 4);
  return h3.compactCells(nearby);
}
```

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

```py
h3.compact_cells(cells)
```

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

```sh
$ h3 compactCells --help
h3: Compacts the provided set of cells as best as possible. The set of input cells must all share the same resolution.
H3 4.1.0

	compactCells	Compacts the provided set of cells as best as possible. The set of input cells must all share the same resolution.
	-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 compact. Up to 100 cells if provided as hexadecimals with zero padding.
	-f, --format <FMT>	'json' for ["CELL", ...], 'newline' for CELL\n... (Default: json)
```

```bash
$ h3 compactCells -c 85283473fffffff,85283447fffffff,8528347bfffffff,85283463fffffff,85283477fffffff,8528340ffffffff,8528340bfffffff,85283457fffffff,85283443fffffff,8528344ffffffff,852836b7fffffff,8528346bfffffff,8528346ffffffff,85283467fffffff,8528342bfffffff,8528343bfffffff,85283407fffffff,85283403fffffff,8528341bfffffff
[ "85283447fffffff", "8528340ffffffff", "8528340bfffffff", "85283457fffffff", "85283443fffffff", "8528344ffffffff", "852836b7fffffff", "8528342bfffffff", "8528343bfffffff", "85283407fffffff", "85283403fffffff", "8528341bfffffff", "8428347ffffffff" ]
```

</TabItem>
</Tabs>

## uncompactCells

Uncompacts the set `compactedSet` of indexes to the resolution `res`.
`h3Set` must be at least of size `uncompactCellsSize(compactedSet, numHexes, res)`.

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

```c
H3Error uncompactCells(const H3Index *compactedSet, const int64_t numCells, H3Index *cellSet, const int64_t maxCells, const int res);
```

Returns 0 (`E_SUCCESS`) on success.

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

```java
List<Long> uncompactCells(Collection<Long> cells, int res);
List<String> uncompactCellAddress(Collection<String> cells, int res);
```

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

```js
h3.uncompactCells(cells, res)
```

```js live
function example() {
  const cell = '85283473fffffff';
  const nearby = h3.gridDisk(cell, 4);
  const compacted = h3.compactCells(nearby);
  return h3.uncompactCells(compacted, 5);
}
```

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

```py
h3.uncompact_cells(cells, res)
```

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

```sh
$ h3 uncompactCells --help
h3: Unompacts the provided set of compacted cells.The uncompacted cells will be printed one per line to stdout.
H3 4.1.0

	uncompactCells	Unompacts the provided set of compacted cells.The uncompacted cells will be printed one per line to stdout.
	-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 uncompact. Up to 100 cells if provided as hexadecimals with zero padding.
	-r, --resolution <res>	Required. Resolution, 0-15 inclusive, that the compacted set should be uncompacted to. Must be greater than or equal to the highest resolution within the compacted set.
	-f, --format <FMT>	'json' for ["CELL", ...], 'newline' for CELL\n... (Default: json)
```

```bash
$ h3 uncompactCells -r 5 -c 85283447fffffff,8528340ffffffff,8528340bfffffff,85283457fffffff,85283443fffffff,8528344ffffffff,852836b7fffffff,8528342bfffffff,8528343bfffffff,85283407fffffff,85283403fffffff,8528341bfffffff,8428347ffffffff
[ "85283447fffffff", "8528340ffffffff", "8528340bfffffff", "85283457fffffff", "85283443fffffff", "8528344ffffffff", "852836b7fffffff", "8528342bfffffff", "8528343bfffffff", "85283407fffffff", "85283403fffffff", "8528341bfffffff", "85283463fffffff", "85283467fffffff", "8528346bfffffff", "8528346ffffffff", "85283473fffffff", "85283477fffffff", "8528347bfffffff" ]
```

</TabItem>
</Tabs>


## uncompactCellsSize

Provides the total resulting number of cells if uncompacting a cell set to
a given resolution.

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

```c
H3Error uncompactCellsSize(const H3Index *compactedSet, const int64_t numCompacted, const int res, int64_t *out);
```

Provides the size of the array needed by `uncompactCells` into `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="shell">

:::note

This function exists for memory management and is not exposed.

:::

</TabItem>
</Tabs>
