Point codes¶

Plus-code and OSM-shortlink codecs using explicit longitude/latitude order.

osm_shortlink_encode ¶

Accepted call forms

osm_shortlink_encode(value: Point, lat: None = None, *, zoom: int | integer[Any] = 16) -> str

osm_shortlink_encode(value: FloatScalar, lat: FloatScalar, *, zoom: int | integer[Any] = 16) -> str

osm_shortlink_encode(value: GeometryArray[Point], lat: None = None, *, zoom: int | integer[Any] = 16) -> list[str]

osm_shortlink_encode(value: GeometryArray[Point | None], lat: None = None, *, zoom: int | integer[Any] = 16) -> list[str | None]

osm_shortlink_encode(value: Sequence[float], lat: FloatInput, *, zoom: int | integer[Any] = 16) -> list[str]

osm_shortlink_encode(value: FloatInput, lat: Sequence[float], *, zoom: int | integer[Any] = 16) -> list[str]

osm_shortlink_encode(value: Buffer, lat: FloatInput, *, zoom: int | integer[Any] = 16) -> str | list[str]

osm_shortlink_encode(value: FloatInput, lat: Buffer, *, zoom: int | integer[Any] = 16) -> str | list[str]

osm_shortlink_encode(value: Iterable[float], lat: FloatInput, *, zoom: int | integer[Any] = 16) -> str | list[str]

osm_shortlink_encode(value: FloatInput, lat: Iterable[float], *, zoom: int | integer[Any] = 16) -> str | list[str]

OpenStreetMap shortlink code of a point.

The compact location code in https://osm.org/go/... URLs (a Morton quadtile path, six bits per character). Accepts a Point/GeometryArray (CRS-aware) or a bare lon, lat pair.

Parameters:

Name	Type	Description	Default
`value`	`Point, GeometryArray, or float`	The point(s) to encode, or a bare longitude.	required
`lat`	`float`	Latitude when `value` is a longitude.	required
`zoom`	`int`	Map zoom the link opens at (`0` to `22`).	`16`

Returns:

Type	Description
`str or list of str`	The shortlink code(s), e.g. `'0EEQjE--'`.

Raises:

Type	Description
`GeometryError`	If `zoom` is out of range.
`InvalidGeometryError`	If a coordinate is non-finite or out of the lon/lat domain.

Examples:

>>> import gometry as gm
>>> gm.osm_shortlink_encode(13.365, 52.5077, zoom=17)
'0MbEUxVoG-'

osm_shortlink_location ¶

Accepted call forms

osm_shortlink_location(code: str) -> tuple[float, float, int]

osm_shortlink_location(code: Iterable[str]) -> tuple[NDArray[float64], NDArray[float64], ndarray[tuple[int], dtype[int64]]]

osm_shortlink_location(code: Iterable[str | None]) -> tuple[NDArray[float64], NDArray[float64], ndarray[tuple[int], dtype[int64]]]

Parse an OSM shortlink code back into its location and zoom.

Accepts the modern ~ spelling and the legacy @ one.

Parameters:

Name	Type	Description	Default
`code`	`str or iterable of str or None`	The shortlink code(s) (the part after `osm.org/go/`).	required

Returns:

Type	Description
`tuple`	Scalar input returns `(lon, lat, zoom)`. Bulk input returns `(lon_array, lat_array, zoom_array)`. Missing rows retain their position with NaN longitude/latitude and zoom `-1`.

Raises:

Type	Description
`ParseError`	If `code` contains characters outside the shortlink alphabet, or is too short/long to name a real zoom level.

Examples:

>>> import gometry as gm
>>> lon, lat, zoom = gm.osm_shortlink_location('0MbEUxVoG-')
>>> round(lon, 3), round(lat, 3), zoom
(13.365, 52.508, 17)

pluscode_encode ¶

Accepted call forms

pluscode_encode(value: Point, lat: None = None, *, length: int | integer[Any] = 10) -> str

pluscode_encode(value: FloatScalar, lat: FloatScalar, *, length: int | integer[Any] = 10) -> str

pluscode_encode(value: GeometryArray[Point], lat: None = None, *, length: int | integer[Any] = 10) -> list[str]

pluscode_encode(value: GeometryArray[Point | None], lat: None = None, *, length: int | integer[Any] = 10) -> list[str | None]

pluscode_encode(value: Sequence[float], lat: FloatInput, *, length: int | integer[Any] = 10) -> list[str]

pluscode_encode(value: FloatInput, lat: Sequence[float], *, length: int | integer[Any] = 10) -> list[str]

pluscode_encode(value: Buffer, lat: FloatInput, *, length: int | integer[Any] = 10) -> str | list[str]

pluscode_encode(value: FloatInput, lat: Buffer, *, length: int | integer[Any] = 10) -> str | list[str]

pluscode_encode(value: Iterable[float], lat: FloatInput, *, length: int | integer[Any] = 10) -> str | list[str]

pluscode_encode(value: FloatInput, lat: Iterable[float], *, length: int | integer[Any] = 10) -> str | list[str]

Plus code (Open Location Code) of a point.

Encodes WGS84 coordinates as Google's Open Location Code — the offline-friendly "plus codes" used where street addresses are missing. Accepts a Point/GeometryArray (CRS-aware, reprojected to lon/lat) or a bare lon, lat pair.

Parameters:

Name	Type	Description	Default
`value`	`Point, GeometryArray, or float`	The point(s) to encode, or a bare longitude.	required
`lat`	`float`	Latitude when `value` is a longitude.	required
`length`	`int`	Significant digits (even from 2 to 10, then 11-15); 10 is roughly a 14 m cell, each pair beyond divides it further.	`10`

Returns:

Type	Description
`str or list of str`	The plus code(s), e.g. `'8FVC2222+22'`.

Raises:

Type	Description
`GeometryError`	If `length` is invalid.
`InvalidGeometryError`	If a coordinate is non-finite.

Notes

Bare longitude/latitude and geometry inputs are validated against the WGS84 lon/lat domain before encoding. Out-of-domain finite coordinates raise InvalidGeometryError rather than silent clip/wrap (the OLC reference clips, but gometry rejects so huge finite inputs cannot mint a code for a different location).

Examples:

>>> import gometry as gm
>>> gm.pluscode_encode(8.628, 47.366)
'8FVC9J8H+C6'

pluscode_polygon ¶

Accepted call forms

pluscode_polygon(code: str) -> Polygon

pluscode_polygon(code: Iterable[str]) -> GeometryArray[Polygon]

pluscode_polygon(code: Iterable[str | None]) -> GeometryArray[Polygon | None]

Return the rectangular cell a plus code covers, as a WGS84 Polygon.

Parameters:

Name	Type	Description	Default
`code`	`str or iterable of str`	A full plus code (e.g. `'8FVC9G8F+6X'`), or one code per row.	required

Returns:

Type	Description
`Polygon or GeometryArray`	The code cell(s), CRS `OGC:CRS84`. Missing code rows produce missing polygons.

Raises:

Type	Description
`ParseError`	If `code` is not a full plus code.

Examples:

>>> import gometry as gm
>>> gm.pluscode_polygon('8FVC9G8F+6X').bounds
(8.524875, 47.3655, 8.525, 47.36562499999999)

pluscode_recover ¶

Accepted call forms

pluscode_recover(code: str, reference: Point, lat: None = None) -> str

pluscode_recover(code: Iterable[str], reference: Point, lat: None = None) -> list[str]

pluscode_recover(code: str, reference: FloatScalar, lat: FloatScalar) -> str

pluscode_recover(code: str, reference: Sequence[float], lat: FloatInput) -> list[str]

pluscode_recover(code: str, reference: FloatInput, lat: Sequence[float]) -> list[str]

pluscode_recover(code: str, reference: Buffer, lat: FloatInput) -> str | list[str]

pluscode_recover(code: str, reference: FloatInput, lat: Buffer) -> str | list[str]

pluscode_recover(code: str, reference: Iterable[float], lat: FloatInput) -> str | list[str]

pluscode_recover(code: str, reference: FloatInput, lat: Iterable[float]) -> str | list[str]

pluscode_recover(code: Iterable[str], reference: FloatInput, lat: FloatInput) -> list[str]

pluscode_recover(code: Iterable[str | None], reference: Point, lat: None = None) -> list[str | None]

pluscode_recover(code: Iterable[str | None], reference: FloatInput, lat: FloatInput) -> list[str | None]

Recover the nearest full plus code from a shortened one.

Parameters:

Name	Type	Description	Default
`code`	`str or iterable of str or None`	A short plus code (e.g. `'9G8F+6X'`); a full code passes through normalized.	required
`reference`	`Point or float`	A CRS-aware reference point or longitude column.	required
`lat`	`float or sequence of float`	Latitude column when `reference` is a longitude. Coordinate columns broadcast with one another and with a scalar code.	required

Returns:

Type	Description
`str or list of str or None`	The full plus code(s) closest to the reference. Missing code rows produce `None` entries.

Raises:

Type	Description
`ParseError`	If `code` is neither a short nor a full plus code.
`InvalidGeometryError`	If `reference`/`lat` are non-finite.

Examples:

>>> import gometry as gm
>>> gm.pluscode_recover('9G8F+6X', 8.5, 47.4)
'8FVC9G8F+6X'
>>> gm.pluscode_recover('9G8F+6X', gm.Point(8.5, 47.4, crs=4326))
'8FVC9G8F+6X'

pluscode_shorten ¶

Accepted call forms

pluscode_shorten(code: str, reference: Point, lat: None = None) -> str

pluscode_shorten(code: Iterable[str], reference: Point, lat: None = None) -> list[str]

pluscode_shorten(code: str, reference: FloatScalar, lat: FloatScalar) -> str

pluscode_shorten(code: str, reference: Sequence[float], lat: FloatInput) -> list[str]

pluscode_shorten(code: str, reference: FloatInput, lat: Sequence[float]) -> list[str]

pluscode_shorten(code: str, reference: Buffer, lat: FloatInput) -> str | list[str]

pluscode_shorten(code: str, reference: FloatInput, lat: Buffer) -> str | list[str]

pluscode_shorten(code: str, reference: Iterable[float], lat: FloatInput) -> str | list[str]

pluscode_shorten(code: str, reference: FloatInput, lat: Iterable[float]) -> str | list[str]

pluscode_shorten(code: Iterable[str], reference: FloatInput, lat: FloatInput) -> list[str]

pluscode_shorten(code: Iterable[str | None], reference: Point, lat: None = None) -> list[str | None]

pluscode_shorten(code: Iterable[str | None], reference: FloatInput, lat: FloatInput) -> list[str | None]

Shorten a full plus code relative to a nearby reference point.

Removes two to six leading digits that the reference location implies; pluscode_recover restores them.

Parameters:

Name	Type	Description	Default
`code`	`str or iterable of str or None`	A full, unpadded plus code with at least 6 digits.	required
`reference`	`Point or float`	A CRS-aware reference point or longitude column.	required
`lat`	`float or sequence of float`	Latitude column when `reference` is a longitude. Coordinate columns broadcast with one another and with a scalar code.	required

Returns:

Type	Description
`str or list of str or None`	The shortened code(s) — or the original when the reference is too far. Missing code rows produce `None` entries.

Raises:

Type	Description
`ParseError`	If `code` is not a full plus code.
`GeometryError`	If the code is padded or has fewer than 6 digits.
`InvalidGeometryError`	If `reference`/`lat` are non-finite.

Examples:

>>> import gometry as gm
>>> gm.pluscode_shorten('8FVC9G8F+6X', 8.5, 47.4)
'9G8F+6X'
>>> gm.pluscode_shorten('8FVC9G8F+6X', gm.Point(8.5, 47.4, crs=4326))
'9G8F+6X'