API Reference

This section provides detailed documentation for all functions available in the PyGeoHash library.

Core Functions

These core functions are implemented using a high-performance C extension for maximum efficiency.

pygeohash.encode(latitude: float, longitude: float, precision: int = 12) → str

Encode a latitude and longitude into a geohash.

Args:

latitude (float): The latitude to encode. longitude (float): The longitude to encode. precision (int, optional): The number of characters in the geohash. Defaults to 12.

Returns:

str: The geohash string.

pygeohash.encode_strictly(latitude: float, longitude: float, precision: int = 12) → str

Encode a latitude and longitude into a geohash with strict midpoint handling.

Args:

latitude (float): The latitude to encode. longitude (float): The longitude to encode. precision (int, optional): The number of characters in the geohash. Defaults to 12.

Returns:

str: The geohash string.

pygeohash.decode(geohash: str) → LatLong

Decode a geohash into a latitude and longitude.

Args:

geohash (str): The geohash string to decode.

Returns:

LatLong: A named tuple containing the latitude and longitude.

pygeohash.decode_exactly(geohash: str) → ExactLatLong

Decode a geohash into a latitude and longitude with error margins.

This function provides more detailed information than the standard decode function by including the error margins for both latitude and longitude.

Args:

geohash (str): The geohash string to decode.

Returns:

ExactLatLong: A named tuple containing the latitude, longitude, and their

respective error margins.

Data Types

class pygeohash.LatLong(latitude: float, longitude: float)

Bases: NamedTuple

Named tuple representing a latitude/longitude coordinate pair.

Attributes:

latitude (float): The latitude coordinate in decimal degrees. longitude (float): The longitude coordinate in decimal degrees.

Create new instance of LatLong(latitude, longitude)

latitude: float

Alias for field number 0

longitude: float

Alias for field number 1

class pygeohash.ExactLatLong(latitude: float, longitude: float, latitude_error: float, longitude_error: float)

Bases: NamedTuple

Named tuple representing a latitude/longitude coordinate pair with error margins.

Attributes:

latitude (float): The latitude coordinate in decimal degrees. longitude (float): The longitude coordinate in decimal degrees. latitude_error (float): The error margin for latitude in decimal degrees. longitude_error (float): The error margin for longitude in decimal degrees.

Create new instance of ExactLatLong(latitude, longitude, latitude_error, longitude_error)

latitude: float

Alias for field number 0

latitude_error: float

Alias for field number 2

longitude: float

Alias for field number 1

longitude_error: float

Alias for field number 3

class pygeohash.BoundingBox(min_lat: float, min_lon: float, max_lat: float, max_lon: float)

Bases: NamedTuple

Named tuple representing a geospatial bounding box.

Attributes:

min_lat (float): The minimum (southern) latitude of the box in decimal degrees. min_lon (float): The minimum (western) longitude of the box in decimal degrees. max_lat (float): The maximum (northern) latitude of the box in decimal degrees. max_lon (float): The maximum (eastern) longitude of the box in decimal degrees.

Create new instance of BoundingBox(min_lat, min_lon, max_lat, max_lon)

max_lat: float

Alias for field number 2

max_lon: float

Alias for field number 3

min_lat: float

Alias for field number 0

min_lon: float

Alias for field number 1

Distance Calculations

pygeohash.geohash_approximate_distance(geohash_1: str, geohash_2: str, check_validity: bool = False) → float

Calculate the approximate great-circle distance between two geohashes.

This function calculates an approximate distance based on the number of matching characters at the beginning of the geohashes. It’s faster but less accurate than haversine distance.

Args:

geohash_1 (str): The first geohash. geohash_2 (str): The second geohash. check_validity (bool, optional): Whether to check if the geohashes are valid.

Defaults to False.

Returns:

float: The approximate distance in meters.

Raises:

ValueError: If check_validity is True and either geohash is invalid.

Example:

>>> geohash_approximate_distance("u4pruyd", "u4pruyf")
118.0

pygeohash.geohash_haversine_distance(geohash_1: str, geohash_2: str) → float

Calculate the haversine great-circle distance between two geohashes.

This function provides a more accurate distance calculation using the haversine formula, which accounts for the Earth’s curvature.

Args:

geohash_1 (str): The first geohash. geohash_2 (str): The second geohash.

Returns:

float: The distance in meters.

Example:

>>> geohash_haversine_distance("u4pruyd", "u4pruyf")
152.3

Geohash Navigation

pygeohash.get_adjacent(geohash: str, direction: str) → str

Calculate the adjacent geohash in the specified direction.

Args:

geohash (str): The input geohash string. direction (str): The direction to find the adjacent geohash.

Must be one of: “right”, “left”, “top”, “bottom”.

Returns:

str: The adjacent geohash in the specified direction.

Raises:

ValueError: If the geohash length is 0 (possible when close to poles).

Example:

>>> get_adjacent("u4pruyd", "top")
'u4pruyf'

Bounding Box Operations

pygeohash.get_bounding_box(geohash: str) → BoundingBox

Calculate the bounding box for a geohash.

Args:

geohash (str): The geohash string to calculate the bounding box for.

Returns:

BoundingBox: A named tuple containing the minimum and maximum latitude and longitude

values that define the bounding box of the geohash.

Example:

>>> get_bounding_box("u4pruyd")
BoundingBox(min_lat=57.649, min_lon=10.407, max_lat=57.649, max_lon=10.407)

Note:

The precision of the coordinates in the bounding box depends on the length of the geohash. Longer geohashes result in smaller bounding boxes with more precise coordinates.

pygeohash.is_point_in_box(lat: float, lon: float, bbox: BoundingBox) → bool

Check if a point is within a bounding box.

Args:

lat (float): The latitude of the point to check. lon (float): The longitude of the point to check. bbox (BoundingBox): The bounding box to check against.

Returns:

bool: True if the point is within the bounding box, False otherwise.

Example:

>>> bbox = get_bounding_box("u4pruyd")
>>> is_point_in_box(57.649, 10.407, bbox)
True
>>> is_point_in_box(40.0, 10.0, bbox)
False

pygeohash.is_point_in_geohash(lat: float, lon: float, geohash: str) → bool

Check if a point is within a geohash’s bounding box.

Args:

lat (float): The latitude of the point to check. lon (float): The longitude of the point to check. geohash (str): The geohash to check against.

Returns:

bool: True if the point is within the geohash’s bounding box, False otherwise.

Example:

>>> is_point_in_geohash(57.649, 10.407, "u4pruyd")
True
>>> is_point_in_geohash(40.0, 10.0, "u4pruyd")
False

pygeohash.do_boxes_intersect(bbox1: BoundingBox, bbox2: BoundingBox) → bool

Check if two bounding boxes intersect.

Args:

bbox1 (BoundingBox): The first bounding box. bbox2 (BoundingBox): The second bounding box.

Returns:

bool: True if the bounding boxes intersect, False otherwise.

Example:

>>> box1 = BoundingBox(10.0, 20.0, 30.0, 40.0)
>>> box2 = BoundingBox(20.0, 30.0, 40.0, 50.0)
>>> do_boxes_intersect(box1, box2)
True

pygeohash.geohashes_in_box(bbox: BoundingBox, precision: int = 6) → List[str]

Find geohashes that intersect with a given bounding box.

Args:

bbox (BoundingBox): The bounding box to find geohashes for. precision (int, optional): The precision of the geohashes to return. Defaults to 6.

Returns:

List[str]: A list of geohashes that intersect with the bounding box.

Example:

>>> box = BoundingBox(57.64, 10.40, 57.65, 10.41)
>>> geohashes_in_box(box, precision=5)
['u4pru', 'u4prv']

Note:

The number of geohashes returned depends on the size of the bounding box and the precision requested. Higher precision values will result in more geohashes for the same bounding box.

Statistical Functions

pygeohash.mean(geohashes: Iterable[str]) → str

Calculate the mean position of a collection of geohashes.

Args:

geohashes (Iterable[str]): Collection of geohash strings.

Returns:

str: A geohash representing the mean position.

Example:

>>> mean(["u4pruyd", "u4pruyf", "u4pruyc"])
'u4pruye'

pygeohash.northern(geohashes: Iterable[str]) → str

Find the northernmost geohash in a collection.

Args:

geohashes (Iterable[str]): Collection of geohash strings.

Returns:

str: The northernmost geohash.

Example:

>>> northern(["u4pruyd", "u4pruyf", "u4pruyc"])
'u4pruyf'

pygeohash.southern(geohashes: Iterable[str]) → str

Find the southernmost geohash in a collection.

Args:

geohashes (Iterable[str]): Collection of geohash strings.

Returns:

str: The southernmost geohash.

Example:

>>> southern(["u4pruyd", "u4pruyf", "u4pruyc"])
'u4pruyc'

pygeohash.eastern(geohashes: Iterable[str]) → str

Find the easternmost geohash in a collection.

Args:

geohashes (Iterable[str]): Collection of geohash strings.

Returns:

str: The easternmost geohash.

Example:

>>> eastern(["u4pruyd", "u4pruyf", "u4pruyc"])
'u4pruyf'

pygeohash.western(geohashes: Iterable[str]) → str

Find the westernmost geohash in a collection.

Args:

geohashes (Iterable[str]): Collection of geohash strings.

Returns:

str: The westernmost geohash.

Example:

>>> western(["u4pruyd", "u4pruyf", "u4pruyc"])
'u4pruyc'

pygeohash.variance(geohashes: Iterable[str]) → float

Calculate the spatial variance of a collection of geohashes.

The variance is calculated as the mean of squared distances from each geohash to the mean position.

Args:

geohashes (Iterable[str]): Collection of geohash strings.

Returns:

float: The spatial variance in square meters.

Example:

>>> variance(["u4pruyd", "u4pruyf", "u4pruyc"])
12500.0

pygeohash.std(geohashes: Iterable[str]) → float

Calculate the spatial standard deviation of a collection of geohashes.

The standard deviation is the square root of the variance.

Args:

geohashes (Iterable[str]): Collection of geohash strings.

Returns:

float: The spatial standard deviation in meters.

Example:

>>> std(["u4pruyd", "u4pruyf", "u4pruyc"])
111.8

Visualization Functions

These functions require additional dependencies that can be installed with: pip install pygeohash[viz]

The visualization module provides tools for creating static plots with Matplotlib and interactive maps with Folium:

pygeohash.plot_geohash(geohash: str, ax=None, color: str = 'red', alpha: float = 0.5, label: str | None = None, show_center: bool = False, show_label: bool = False, **kwargs) → Tuple

Plot a single geohash on a map.

Args:

geohash: The geohash string to plot ax: Matplotlib axis to plot on (optional) color: Color of the geohash polygon alpha: Transparency of the geohash polygon label: Label for the geohash (defaults to the geohash string) show_center: Whether to show the center point of the geohash show_label: Whether to show the label on the map **kwargs: Additional keyword arguments passed to matplotlib

Returns:

Tuple: (fig, ax) - The matplotlib figure and axis objects

Examples:

>>> import pygeohash as pgh
>>> from pygeohash.viz import plot_geohash
>>> fig, ax = plot_geohash("9q8yyk")

pygeohash.plot_geohashes(geohashes: List[str], ax=None, colors: str | List[str] = 'viridis', alpha: float = 0.5, labels: List[str] | None = None, show_centers: bool = False, show_labels: bool = False, **kwargs) → Tuple

Plot multiple geohashes on a map.

Args:

geohashes: List of geohash strings to plot ax: Matplotlib axis to plot on (optional) colors: Color or colormap name for the geohashes alpha: Transparency of the geohash polygons labels: Labels for the geohashes (defaults to the geohash strings) show_centers: Whether to show the center points of the geohashes show_labels: Whether to show the labels on the map **kwargs: Additional keyword arguments passed to matplotlib

Returns:

Tuple: (fig, ax) - The matplotlib figure and axis objects

Examples:

>>> import pygeohash as pgh
>>> from pygeohash.viz import plot_geohashes
>>> fig, ax = plot_geohashes(["9q8yyk", "9q8yym", "9q8yyj"])

pygeohash.folium_map(center_geohash: str | None = None, center: Tuple[float, float] | None = None, zoom_start: int = 13, tiles: str = 'OpenStreetMap', width: str = '100%', height: str = '100%')

Create an interactive map with geohashes using Folium.

Args:

center_geohash: Geohash string to center the map on center: (lat, lon) tuple to center the map on (alternative to center_geohash) zoom_start: Initial zoom level tiles: Map tile provider width: Width of the map height: Height of the map

Returns:

folium.Map: A Folium map object with methods to add geohashes

Examples:

>>> import pygeohash as pgh
>>> from pygeohash.viz import folium_map
>>> m = folium_map(center_geohash="9q8yyk")
>>> m.add_geohash("9q8yyk", color="red", fill=True)
>>> m.save("geohash_map.html")

For detailed examples of how to use these functions, see the Examples section.