Geohash¶

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

Types¶

GeohashCell ¶

Accepted call forms

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

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

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

precision: int

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

Returns:

Type	Description
`int`

children ¶

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:

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

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:

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

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:

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

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:

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

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:

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

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:

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

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]

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.

geohash_cover ¶

Accepted call forms

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

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]

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:

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

geohash_difference ¶

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:

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

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:

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

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:

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

Geohash¶

Types¶

GeohashCell ¶

precision property ¶

children ¶

children_count ¶

contains ¶

intersects ¶

parent ¶

Functions¶

geohash_bounding_cell ¶

geohash_cells ¶

geohash_cover ¶

geohash_difference ¶

geohash_intersection ¶

geohash_union ¶

precision `property` ¶