DOCSEARCHbyAlgolia
Submit Docs

PyGeoHash 3.5.1

repository·master·Indexed 41 days ago

https://github.com/wdm0006/pygeohash

A high-performance Python library implemented as a C extension for encoding and decoding geographic coordinates into geohashes. It provides utilities for calculating approximate and Haversine distances, retrieving adjacent geohashes, and performing bounding box operations. PyGeoHash also supports conversions between geohashes, Bing Quadkeys, and map-tiles, as well as visualization support via Matplotlib and Folium.

Tokens
18.9K
Snippets
69
Records
87
Agent score
49%

What's inside PyGeoHash

  1. What is PyGeoHash?

    master
    PyGeoHash is a Python module designed for encoding and decoding geohashes to and from latitude and longitude coordinates. It includes utilities for performing spatial calculations and approximations. It is a modernized, Python 3-compatible version of Leonard Norrgård's geohash module, featuring core operations implemented in C for high performance.

  2. Compare PyGeoHash performance with other libraries

    master
    PyGeoHash is implemented as a C extension, making it significantly faster than pure-Python implementations like libgeohash or geolib. In benchmark tests, it is approximately 1.10x faster than python-geohash and 13.4x faster than libgeohash for encoding operations. It is noted for high stability (low run-to-run spread) across most operations, including bounding box lookups and box enumeration.

  3. Use Geohash bounding boxes for spatial queries

    master

    Every geohash represents a rectangular area on Earth, defined by a bounding box consisting of:

    • Minimum latitude (southern edge)
    • Minimum longitude (western edge)
    • Maximum latitude (northern edge)
    • Maximum longitude (eastern edge)

    Bounding boxes are essential for:

    1. Spatial Queries: Finding all points within a specific geographic region.
    2. Geofencing: Determining if a point is inside or outside a defined area.
    3. Spatial Indexing: Efficiently organizing and querying spatial data.
    4. Visualization: Rendering geographic data on maps.

    By using bounding boxes, you can determine the exact area covered by a geohash, find intersecting geohashes, and check for overlapping geographic regions.

  4. Choose between Geohash, Slippy Tiles, and H3/S2

    master

    When deciding on a spatial indexing system, consider the following use cases:

    • Geohash: Best for storage, sharding keys, and bounding queries. It encodes latitude/longitude rectangles as base32 strings and is highly performant due to its C extension.
    • Slippy Tiles (z/x/y) and Quadkeys: The standard for web maps. Use these when working with tile-based map displays. Quadkeys are base-4 digit strings representing the nesting path of tiles.
    • H3 (Hexagons) and S2 (Spherical cells): Use these directly if your problem requires hexagonal neighborhood geometry, spherical region covering, or specific cell hierarchies. pygeohash does not convert to H3 or S2 to avoid false promises of grid alignment.

    Use pygeohash.interop when you need to move data between geohash storage and the map-tile ecosystem without adding new dependencies.

  5. Performance and precision considerations

    master

    When using PyGeoHash, keep the following performance and accuracy notes in mind:

    • Speed: Geohash operations are highly efficient due to a C extension implementation.
    • Scale: For datasets involving millions of geohashes, it is recommended to use a database with native geospatial capabilities rather than in-memory processing.
    • Visualization: Plotting functions may experience slowdowns with very large numbers of geohashes. Consider limiting the number of displayed items or using a lower precision for visualization.
    • Edge Cases: Be aware of geohash precision limitations when working near the Earth's poles or the 180° meridian.

  6. Unique features in PyGeoHash

    master

    While many libraries provide basic encoding and decoding, pygeohash provides several unique utility functions that are not available in common competitors like geohashr, python-geohash, or geolib. These include:

    • Quadkey conversions: Converting between geohashes and quadkeys (geohash_to_quadkey and quadkey_to_geohash).
    • Tile round-tripping: Converting a geohash to a tile and back (geohash_to_tile and tile_to_geohash).
    • Box enumeration: Finding all geohashes within a specific bounding box (geohashes_in_box).
    • Standalone validation: Checking if a geohash string is valid (is_valid_geohash).

  7. Understand Geohash concepts and properties

    master

    A geohash is a geocoding system that encodes latitude and longitude into a short string of base-32 characters. It is primarily used for indexing and searching geographic data due to several key properties:

    • Hierarchical: Locations that share a common prefix are geographically close to each other. Note that while similar prefixes imply proximity, the reverse is not always true (points can be close but have different prefixes due to grid boundaries).
    • Arbitrary Precision: You can control the precision of the location by adjusting the length of the geohash string.
    • Compact & Human-Readable: Efficient for storage and easy to communicate.

    Limitations to Consider

    • Edge Effects: Points very close to each other might fall on opposite sides of a grid boundary, resulting in completely different geohash strings. When searching for nearby locations, you should check adjacent geohash cells.
    • Longitude Wrapping: Points near the 180° meridian may have significantly different geohashes.
    • Non-Uniform Area: The physical area of a geohash cell varies depending on the latitude (precision decreases near the poles).

  8. Understand conversion semantics and limitations

    master

    When converting between Geohashes and Slippy Tiles, be aware of the following behaviors:

    Longitude and Precision

    Longitude is exact between the two grids. An even-precision geohash at zoom 5 * precision / 2 maps cell-for-cell to a tile column and back losslessly. Generally, precision p maps to zoom floor(5 * p / 2).

    Latitude and Web Mercator

    Latitude is not perfectly aligned. Geohash latitude bands are equirectangular, while tile rows use Web Mercator projection. A round trip through non-aligned zoom or precision levels may land in a neighboring geohash cell. Boundary centers resolve deterministically to the lower-x, lower-y cell.

    The Poles

    Geohashes cover up to +/-90 degrees, but tiles only exist within approximately +/-85.05112878 degrees.

    • By default, converting a cell whose center is outside the tile band raises a ValueError.
    • To map it to the nearest in-band tile row instead, use clip=True (where supported).

  9. Reproduce the PyGeoHash benchmarks

    master

    To reproduce the benchmark results on your own machine, you must have the repository checked out locally and install the project with both the dev and benchmark extras. You can then run the comparison script provided in the repository.

    Note that the benchmark script performs a warmup pass, runs the suite multiple times, and uses pytest-benchmark JSON reports to update the documentation with the observed environment and performance figures. It is recommended to run this on your own hardware before quoting any performance figures.

    uv pip install -e ".[dev,benchmark]"
python scripts/run_comparison_benchmark.py

  11. Install pygeohash

    master

    You can install pygeohash using pip. Depending on your needs, you can install the base library, include visualization support, or include benchmark dependencies.

    Basic installation

    pip install pygeohash

    With visualization support

    pip install pygeohash[viz]

    With cross-library benchmark comparison dependencies

    pip install pygeohash[benchmark]
    # Basic installation
pip install pygeohash

# With visualization support
pip install pygeohash[viz]

# With the cross-library benchmark comparison dependencies
pip install pygeohash[benchmark]

  12. Install visualization dependencies

    master

    To use the pygeohash.viz module for plotting geohashes with Matplotlib or creating interactive maps with Folium, you must install the optional visualization dependencies.

    You can install them via pip:

    pip install pygeohash[viz]

    If you are working within the repository source, you can also use the provided Makefile commands:

    # Install visualization dependencies
make install-viz

# Generate visualization examples
make viz-examples