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

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

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

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

```py
h3.cell_to_parent(cell, parent_res)
```

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

```java
long cellToParent(long cell, int parentRes);
String cellToParent(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>
</Tabs>

Provides the parent (coarser) index containing `cell`.

Returns 0 (`E_SUCCESS`) on success.

## cellToChildren

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

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

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

```py
h3.cell_to_children(cell, child_res)
```

</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>
</Tabs>

Populates `children` with the indexes contained by `cell` at resolution `childRes`. `children` must be an array of at least size `cellToChildrenSize(cell, childRes)`.

Returns 0 (`E_SUCCESS`) on success.

## cellToChildrenSize

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

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

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

:::note

This function exists for memory management and is not exposed.

:::

</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>
</Tabs>

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

Returns 0 (`E_SUCCESS`) on success.

## cellToCenterChild

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

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

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

```py
h3.cell_to_center_child(cell, child_res)
```

</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>
</Tabs>

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

Returns 0 (`E_SUCCESS`) on success.

## cellToChildPos

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

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

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

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

</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>
</Tabs>

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

Returns 0 (`E_SUCCESS`) on success.

## childPosToCell

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

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

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

```py
h3.cell_to_child_pos(child_pos, parent, child_res)
```

</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>
</Tabs>

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

Returns 0 (`E_SUCCESS`) on success.

## compactCells

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

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

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

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

</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>
</Tabs>

Compacts the set `cellSet` of indexes as best as possible, into the array `compactedSet`. `compactedSet` must be at least the size of `cellSet` in case the set cannot be compacted. Cells in `cellSet` must all share the same resolution.

Returns 0 (`E_SUCCESS`) on success.

## uncompactCells

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

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

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

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

</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.compact(nearby);
  return h3.uncompactCells(compacted, 5);
}
```

</TabItem>
</Tabs>

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

Returns 0 (`E_SUCCESS`) on success.

## uncompactCellsSize

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

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

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

:::note

This function exists for memory management and is not exposed.

:::

</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>
</Tabs>

Places the size of the array needed by `uncompactCells` into `out`.

Returns 0 (`E_SUCCESS`) on success.
