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

# Point codes

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

**Related:** [Grids & geocodes](https://gometry.monicz.dev/guide/grids/)

## osm\_shortlink\_encode

Accepted call forms

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

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

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

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

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

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

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

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

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

```python
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:

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

## osm\_shortlink\_location

Accepted call forms

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

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

```python
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:

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

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

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

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

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

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

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

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

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

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

```python
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:

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

## pluscode\_polygon

Accepted call forms

```python
pluscode_polygon(code: str) -> Polygon
```

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

```python
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:

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

## pluscode\_recover

Accepted call forms

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

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

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

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

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

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

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

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

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

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

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

```python
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:

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

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

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

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

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

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

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

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

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

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

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

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

```python
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:

```pycon
>>> 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'
```