Source: https://gometry.monicz.dev/api/geohash/

# Geohash

Geohash tokens, rectangular cells, neighbors, and area covers.

**Related:** [Grid-generic API](https://gometry.monicz.dev/api/grids/)

## Types

## GeohashCell

Accepted call forms

```python
GeohashCell(value: GeohashCell | str, /) -> GeohashCell
```

```python
GeohashCell(value: Point, /, *, precision: int) -> GeohashCell
```

```python
GeohashCell(value: FloatScalar | ScalarFloatArray, /, lat: FloatScalar | ScalarFloatArray, *, precision: int | integer[Any]) -> GeohashCell
```

One geohash cell: a base-32 character prefix addressing a lon/lat
rectangle.

Wraps the packed cell with typed accessors (`cell.precision`,
`cell.token`, `cell.polygon`, `cell.center`) and hierarchy moves
(`parent`/`children`/`neighbors`). Geohash tokens are the public
identity — text, not integers. Convert via `GeohashCell(...)`.

One geohash cell from a token, lon/lat pair, or point geometry.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `value` | `GeohashCell \| str \| Point \| (FloatScalar \| ScalarFloatArray)` | An existing cell, token, longitude of a `lon, lat` pair, or a point geometry. | *required* |
| `precision` | `int \| (int \| integer[Any])` | Geohash precision (`1`-`12`); required for coordinate construction. | `varies by call form` |
| `lat` | `FloatScalar \| ScalarFloatArray` | Latitude when `value` is a scalar longitude. | `varies by call form` |

Returns:

| Type | Description |
| --- | --- |
| `GeohashCell` |  |

Raises:

| Type | Description |
| --- | --- |
| `ParseError` | If `value` is not a valid geohash token. |
| `GeometryError` | If `precision` is out of range. |
| `InvalidGeometryError` | If a scalar coordinate is non-finite or out of range. |

### precision `property`

```python
precision: int
```

Geohash precision of this cell (`1`-`12` characters).

Returns:

| Type | Description |
| --- | --- |
| `int` |  |

### children

```python
children(precision: int | None = None) -> CellArray[GeohashCell]
```

Child cells at a finer precision.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `precision` | `int` | Target precision; must not be coarser than this cell's. Defaults to one finer than this cell's precision; a maximum-depth cell has no children and yields an empty CellArray. | `None` |

Returns:

| Type | Description |
| --- | --- |
| `CellArray of GeohashCell` | The descendant cells in the grid's public identity order. |

Raises:

| Type | Description |
| --- | --- |
| `GeometryError` | If the target depth is invalid for this cell. |

Examples:

```pycon
>>> import gometry as gm
>>> cell = gm.geohash_cover(gm.Point(-122.4194, 37.7749, crs=4326), precision=6)[0]
>>> assert cell is not None
>>> len(cell.children())
32
```

### children\_count

```python
children_count(precision: int | None = None) -> int
```

Number of descendant cells at a finer precision, counted closed-form without materializing them.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `precision` | `int` | Target precision; must not be coarser than this cell's. Defaults to one finer than this cell's precision; a maximum-depth cell has no children and returns `0`. | `None` |

Returns:

| Type | Description |
| --- | --- |
| `int` | The exact descendant count. |

Raises:

| Type | Description |
| --- | --- |
| `GeometryError` | If the target depth is coarser than this cell's, or invalid. |

Examples:

```pycon
>>> import gometry as gm
>>> cell = gm.geohash_cover(gm.Point(-122.4194, 37.7749, crs=4326), precision=6)[0]
>>> assert cell is not None
>>> cell.children_count()
32
```

### contains

```python
contains(other: GeohashCell | str) -> bool
```

Test whether this cell contains another cell (itself, or any
descendant of it in the cell hierarchy).

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `other` | `GeohashCell or str` | The candidate cell. | *required* |

Returns:

| Type | Description |
| --- | --- |
| `bool` |  |

Raises:

| Type | Description |
| --- | --- |
| `ParseError` | If a cell or token is not a valid cell. |
| `TypeError` | If `other` is not a valid cell object or token. |

Examples:

```pycon
>>> import gometry as gm
>>> cell = gm.geohash_cover(gm.Point(-122.4194, 37.7749, crs=4326), precision=6)[0]
>>> assert cell is not None
>>> cell.contains(cell)
True
```

### intersects

```python
intersects(other: GeohashCell | str) -> bool
```

Test whether this cell intersects another cell (one contains the
other — hierarchy cells cannot partially overlap).

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `other` | `GeohashCell or str` | The candidate cell. | *required* |

Returns:

| Type | Description |
| --- | --- |
| `bool` |  |

Raises:

| Type | Description |
| --- | --- |
| `ParseError` | If a cell or token is not a valid cell. |
| `TypeError` | If `other` is not a valid cell object or token. |

Examples:

```pycon
>>> import gometry as gm
>>> cell = gm.geohash_cover(gm.Point(-122.4194, 37.7749, crs=4326), precision=6)[0]
>>> assert cell is not None
>>> cell.intersects(cell.parent())
True
```

### parent

```python
parent(precision: int | None = None) -> GeohashCell
```

Parent cell at a coarser precision.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `precision` | `int` | Target precision; must not be finer than this cell's. Defaults to one coarser than this cell's precision. | `None` |

Returns:

| Type | Description |
| --- | --- |
| `GeohashCell` | The ancestor cell. |

Raises:

| Type | Description |
| --- | --- |
| `GeometryError` | If the target depth is invalid for this cell. |

Examples:

```pycon
>>> import gometry as gm
>>> cell = gm.geohash_cover(gm.Point(-122.4194, 37.7749, crs=4326), precision=6)[0]
>>> assert cell is not None
>>> cell.parent().token
'9q8yy'
```

## Functions

## geohash\_bounding\_cell

```python
geohash_bounding_cell(value: Geometry | GeometryArray[Geometry | None] | Iterable[float]) -> GeohashCell
```

Return the deepest single geohash cell containing a geometry or lon/lat bounds.

Descends the cell containing the lower corner and accepts it only after its
complete rectangle contains both axes of the query. There is no global
wrapped geohash cell, so an antimeridian-spanning region has no single-cell
result and raises.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `value` | `Geometry, GeometryArray, or sequence of float` | A geometry/array (non-WGS84 frames reproject), or a bare lon/lat `(minx, miny, maxx, maxy)` bounds. | *required* |

Returns:

| Type | Description |
| --- | --- |
| `GeohashCell` | The deepest cell whose rectangle contains the whole bounds. |

Raises:

| Type | Description |
| --- | --- |
| `InvalidGeometryError` | If the geometry is empty or coordinates leave the lon/lat domain. |
| `GeometryError` | If no single geohash cell contains the bounds, or bare bounds are not ordered min <= max. |

Examples:

```pycon
>>> import gometry as gm
>>> berlin = gm.box(13.3, 52.4, 13.5, 52.6, crs=4326)
>>> gm.geohash_bounding_cell(berlin).token
'u33'
```

## geohash\_cells

Accepted call forms

```python
geohash_cells(values: GeometryArray[Point] | Iterable[Point] | (Sequence[Sequence[float]] | ndarray[tuple[int, int], dtype[floating[Any] | signedinteger[Any] | unsignedinteger[Any] | bool_]]) | FloatInput, lat: FloatInput | None = None, *, precision: int | integer[Any] | ndarray[tuple[()], dtype[signedinteger[Any] | unsignedinteger[Any]]] | ndarray[tuple[int], dtype[signedinteger[Any] | unsignedinteger[Any]]] | Iterable[int] | Buffer) -> CellArray[GeohashCell]
```

```python
geohash_cells(values: GeometryArray[Point | None] | Iterable[Point | None], lat: None = None, *, precision: int | integer[Any] | ndarray[tuple[()], dtype[signedinteger[Any] | unsignedinteger[Any]]] | ndarray[tuple[int], dtype[signedinteger[Any] | unsignedinteger[Any]]] | Iterable[int] | Buffer) -> CellArray[GeohashCell | None]
```

Build geohash cells from points, coordinate rows, or parallel lon/lat columns.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `values` | `GeometryArray of Point, iterable of Point or None, coordinate matrix, or float` | Point geometries (`None` makes a missing cell), a coordinate matrix with at least two columns, or WGS84 longitudes. Iterable points must share one CRS and epoch; projected point inputs are reprojected to WGS84. Coordinate matrices use only X and Y, ignoring extra ordinates. | *required* |
| `lat` | `float or sequence of float` | WGS84 latitude per row when `values` supplies longitudes. Coordinate columns broadcast numpy-style; at least one must be a sequence. | `None` |
| `precision` | `int or sequence of int` | Geohash precision (1-12 characters; finer at higher values). A scalar broadcasts to every row; an array supplies one precision per row. | *required* |

Returns:

| Type | Description |
| --- | --- |
| `CellArray of GeohashCell` | One cell per input coordinate. |

Raises:

| Type | Description |
| --- | --- |
| `GeometryError` | If the input is scalar, precision is invalid, or coordinate columns have different lengths. |
| `InvalidGeometryError` | If coordinates are non-finite or leave the lon/lat domain. |

See Also

[GeohashCell](https://gometry.monicz.dev/api/geohash/#gometry.GeohashCell "GeohashCell") : Build a single cell.

Examples:

```pycon
>>> import gometry as gm
>>> gm.GeohashCell(112.5584, 37.8324, precision=9).token
'ww8p1r4t8'
```

## geohash\_cover

Accepted call forms

```python
geohash_cover(geom: GeometryArray[Geometry] | Iterable[Geometry], precision: int, *, cell_rule: Literal['center', 'within', 'overlap', 'bbox'] = 'overlap', max_cells: int | None = 1000000) -> Groups[CellArray[GeohashCell]]
```

```python
geohash_cover(geom: GeometryArray[Geometry | None] | Iterable[Geometry | None], precision: int, *, cell_rule: Literal['center', 'within', 'overlap', 'bbox'] = 'overlap', max_cells: int | None = 1000000) -> Groups[CellArray[GeohashCell] | None]
```

```python
geohash_cover(geom: Geometry, precision: int, *, cell_rule: Literal['center', 'within', 'overlap', 'bbox'] = 'overlap', max_cells: int | None = 1000000) -> CellArray[GeohashCell]
```

Cover a geometry with geohash cells at a fixed precision.

The result is a `CellArray` for scalar input or `Groups[CellArray]` for
array input, with geohash cells selected by `cell_rule`.
Keep the source geometry separately and use the free `gm.*` predicates
for exact geometry questions.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `geom` | `Geometry, GeometryArray, or iterable of Geometry or None` | Geometry to cover (WGS84 lon/lat or projected). A scalar returns a flat cell array; an array or iterable returns one group per input row. `None` produces a missing group; a present empty geometry produces an empty group. | *required* |
| `precision` | `int` | Geohash precision (`1`-`12`; finer at higher values). | *required* |
| `cell_rule` | `('within', 'center', 'overlap', 'bbox')` | Which cells to materialize. `'within'` selects cells entirely inside; `'center'` selects cells whose center is inside; `'overlap'` selects every cell touching the geometry; and `'bbox'` selects every cell meeting the geometry's envelope (one window per part, split at the antimeridian). The rule never affects exact predicates. | `'within'` |
| `max_cells` | `int or None` | Hard cap on returned cells and retained result allocation. Discarded candidates do not consume it; array calls apply it cumulatively across groups. Pass `None` for unlimited output (bounded only by memory). | `1000000` |

Returns:

| Type | Description |
| --- | --- |
| `CellArray or Groups[CellArray]` | A scalar returns a `CellArray`; an array returns one `CellArray` group per input geometry. |

Raises:

| Type | Description |
| --- | --- |
| `GeometryError` | If the geometry, precision, `cell_rule`, or `max_cells` is invalid, or if the returned coverage would exceed `max_cells`. |
| `InvalidGeometryError` | If the geometry is empty. |

Examples:

```pycon
>>> import gometry as gm
>>> point = gm.Point(1, 1)
>>> cells = gm.geohash_cover(point, precision=1)
>>> len(cells)
1
```

## geohash\_difference

```python
geohash_difference(left: GeohashCell | str | Iterable[GeohashCell | str | None], right: GeohashCell | str | Iterable[GeohashCell | str | None]) -> CellArray[GeohashCell]
```

Hierarchy-aware difference of two geohash cell sets.

Cells of `left` partially covered by `right` split into children
until the remainder is exact; the result is normalized in the grid's
public identity order.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `left` | `GeohashCell, str, or iterable of those with missing values skipped` | The two cell sets (any mix of cell objects or tokens). | *required* |
| `right` | `GeohashCell, str, or iterable of those with missing values skipped` | The two cell sets (any mix of cell objects or tokens). | *required* |

Returns:

| Type | Description |
| --- | --- |
| `CellArray of GeohashCell` |  |

Raises:

| Type | Description |
| --- | --- |
| `ParseError` | If a cell or token is not a valid geohash cell. |

Examples:

```pycon
>>> import gometry as gm
>>> p = gm.Point(-122.4194, 37.7749, crs=4326)
>>> cells = [cell for cell in gm.geohash_cover(p, precision=6) if cell is not None]
>>> len(gm.geohash_difference(cells, []))
1
```

## geohash\_intersection

```python
geohash_intersection(left: GeohashCell | str | Iterable[GeohashCell | str | None], right: GeohashCell | str | Iterable[GeohashCell | str | None]) -> CellArray[GeohashCell]
```

Hierarchy-aware intersection of two geohash cell sets.

A cell survives where the two sets overlap; ancestor/descendant overlap
keeps the finer cell.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `left` | `GeohashCell, str, or iterable of those with missing values skipped` | The two cell sets (any mix of cell objects or tokens). | *required* |
| `right` | `GeohashCell, str, or iterable of those with missing values skipped` | The two cell sets (any mix of cell objects or tokens). | *required* |

Returns:

| Type | Description |
| --- | --- |
| `CellArray of GeohashCell` |  |

Raises:

| Type | Description |
| --- | --- |
| `ParseError` | If a cell or token is not a valid geohash cell. |

Examples:

```pycon
>>> import gometry as gm
>>> p = gm.Point(-122.4194, 37.7749, crs=4326)
>>> cells = [cell for cell in gm.geohash_cover(p, precision=6) if cell is not None]
>>> len(gm.geohash_intersection(cells, cells))
1
```

## geohash\_union

```python
geohash_union(left: GeohashCell | str | Iterable[GeohashCell | str | None], right: GeohashCell | str | Iterable[GeohashCell | str | None]) -> CellArray[GeohashCell]
```

Hierarchy-aware union of two geohash cell sets.

Returns the normalized cell union in the grid's public identity
order: contained cells are absorbed by their ancestors and complete
sibling groups are merged into parents.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `left` | `GeohashCell, str, or iterable of those with missing values skipped` | A single cell identity or a collection on either side (any accepted mix of cell objects and identity values for this grid). | *required* |
| `right` | `GeohashCell, str, or iterable of those with missing values skipped` | A single cell identity or a collection on either side (any accepted mix of cell objects and identity values for this grid). | *required* |

Returns:

| Type | Description |
| --- | --- |
| `CellArray of GeohashCell` |  |

Raises:

| Type | Description |
| --- | --- |
| `ParseError` | If a cell or token is not a valid geohash cell. |

Examples:

```pycon
>>> import gometry as gm
>>> p = gm.Point(-122.4194, 37.7749, crs=4326)
>>> cells = [cell for cell in gm.geohash_cover(p, precision=6) if cell is not None]
>>> len(gm.geohash_union(cells, cells))
1
```