rtree-geodetic

Python bindings for rstar_geodetic, a geodetic (longitude/latitude) R-tree with great-circle and WGS84 nearest-neighbour and radius queries over point, linestring, and polygon geometries.

Each (lon, lat) is mapped to a unit vector on the sphere and indexed in an R-tree, so the antimeridian and the poles are ordinary interior points. Coordinates are longitude first, latitude second, in degrees; distances are returned in metres. Queries return integer input positions.

Install

pip install rtree-geodetic

Wheels are built for CPython 3.10 and newer (a single abi3 wheel per platform).

Quick start

A tree is built from any iterable of geometry-likes: (lon, lat) pairs, GeoJSON mappings, objects exposing __geo_interface__ (shapely geometries), or a single object whose __geo_interface__ is a collection (a geopandas GeoSeries, a shapely Multi*, a GeometryCollection, or a FeatureCollection).

from rtree_geodetic import GeodeticPointTree

tree = GeodeticPointTree([
    (-0.1278, 51.5074),  # 0 London
    (2.3522, 48.8566),   # 1 Paris
    (13.4050, 52.5200),  # 2 Berlin
])

tree.nearest((4.9041, 52.3676))                 # 0 (London)
tree.nearest_with_distance((4.9041, 52.3676))   # (0, 357888.0)  metres
tree.within_distance((4.9041, 52.3676), 400_000.0)                      # [0, 1]
tree.within_distance((4.9041, 52.3676), 400_000.0, return_distance=True)
# [(0, 357888.0), (1, 430123.5)]

tree.geometry(0).__geo_interface__
# {'type': 'Point', 'coordinates': (-0.1278, 51.5074)}

Point trees also offer a longitude/latitude rectangle query. Order the corners west-then-east to cross the antimeridian (the GeoJSON RFC 7946 convention):

tree = GeodeticPointTree([(179.0, 0.0), (-178.0, 1.0), (0.0, 0.0)])
tree.in_rectangle((170.0, -10.0), (-170.0, 10.0))   # [0, 1] (the two near the seam)

Linestring and polygon trees measure the minimum great-circle distance to the geometry (zero for a query inside a polygon):

from rtree_geodetic import GeodeticLineStringTree, GeodeticPolygonTree

lines = GeodeticLineStringTree([[(0, 0), (1, 1), (2, 0)], [(10, 10), (11, 11)]])
lines.nearest((1.0, 0.5))                       # 0

square = [[(0, 0), (10, 0), (10, 10), (0, 10), (0, 0)]]
polys = GeodeticPolygonTree([square])
polys.nearest_with_distance((5.0, 5.0))         # (0, 0.0) -- inside

shapely and geopandas

The geometry views expose __geo_interface__, so shapely.geometry.shape reconstructs them, and trees accept shapely geometries and geopandas GeoSeries directly:

import geopandas as gpd
from shapely.geometry import Point, shape
from rtree_geodetic import GeodeticPointTree

series = gpd.GeoSeries([Point(-0.1278, 51.5074), Point(2.3522, 48.8566)])
tree = GeodeticPointTree(series)

index = tree.nearest(Point(2.0, 49.0))          # 1 (Paris)
geom = shape(tree.geometry(index).__geo_interface__)   # a shapely Point

Distance semantics

Distances are great-circle metres. By default they use a spherical Earth (the GRS80 mean radius, 6 371 008.8 m); against an ellipsoid the error is at most about 0.5%.

GeodeticPointTree also offers exact WGS84-ellipsoid geodesic distances (Karney's method) through nearest_wgs84, nearest_with_distance_wgs84, and within_distance_wgs84:

tree.nearest_with_distance_wgs84((4.9041, 52.3676))   # (0, 358968.7) geodesic metres

Invalid coordinates or geometry (an out-of-range longitude or latitude, a non-finite value, too few vertices, an edge spanning half the sphere, or an unclosed ring) raise GeodeticError, a subclass of ValueError.

Performance

Measured with benchmarks/bench.py (uv run --group bench python benchmarks/bench.py; seeded synthetic data, Apple M2 Pro, Python 3.14, shapely 2.1.2, rtree 1.4.1, release build).

One million points distributed uniformly on the sphere, 10,000 queries:

Operation rtree-geodetic shapely STRtree Rtree
Build 0.79 s 0.23 s 1.63 s
Nearest neighbour, per call 3.5 us 7.9 us 21.4 us
Nearest neighbour, WGS84 geodesic 2.6 us not offered not offered
Within 50 km (radius query, ~16 hits) 10.5 us 10.3 us* not offered

100,000 small linestrings and polygons, 2,000 queries:

Operation rtree-geodetic shapely STRtree
Linestring build 0.66 s 0.02 s
Linestring nearest, per call 4.4 us 11.1 us
Polygon build 2.44 s 0.02 s
Polygon nearest, per call 7.8 us 12.6 us

[!NOTE] The planar libraries index raw degrees, so their distances are in degrees and their results degrade away from the equator: on this dataset the STRtree nearest neighbour is geodesically wrong for 10.9% of queries, and the starred radius query (an equator-equivalent degree radius) returns the wrong set at other latitudes. Shapely's batch query_nearest amortises the Python boundary to 5.7 us per query at 1M points; rtree-geodetic offers per-call queries only.

rtree-geodetic build times include coordinate validation and, for linestrings and polygons, per-edge great-circle envelopes; construction traverses Python objects, so a numpy / GeoArrow fast path is future work.

Licence

Licensed under either of Apache License, Version 2.0 or MIT licence at your option.

Project links

Data verified by PyPI on Aug 24, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for urschrei from gravatar.com urschrei

Credits

Author/Maintainer: Stephan Hügel

GitHub Statistics

Data verified by PyPI on Aug 24, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

MIT OR Apache-2.0
View SPDX License List

Requires

Python >=3.10

Tags

rtree r-tree geodetic spatial spatial-index geospatial geo gis nearest-neighbour great-circle geodesic wgs84 haversine geo-interface shapely geopandas

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

rtree_geodetic-0.2.1.tar.gz (188.5 kB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

rtree_geodetic-0.2.1-cp310-abi3-win_amd64.whl (246.0 kB view details)

Uploaded CPython 3.10+Windows x86-64

rtree_geodetic-0.2.1-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (408.6 kB view details)

Uploaded CPython 3.10+manylinux: glibc 2.17+ x86-64

rtree_geodetic-0.2.1-cp310-abi3-macosx_11_0_arm64.whl (357.1 kB view details)

Uploaded CPython 3.10+macOS 11.0+ ARM64

File details

Details for the file rtree_geodetic-0.2.1.tar.gz.

File metadata

  • Download URL: rtree_geodetic-0.2.1.tar.gz
  • Upload date:
  • Size: 188.5 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for rtree_geodetic-0.2.1.tar.gz
Algorithm Hash digest
SHA256 0c7559baf38a1603449d7a94d03a6809f19ffae10ffd206c686c33bfe99f4da0
MD5 62d497c1454f44335174248d5556b87f
BLAKE2b-256 657dfe62f91d560ff421622baf1b88e5a21ca2ed7279a3257d61adbfc833adff

See more details on using hashes here.

Provenance

The following attestation bundles were made for rtree_geodetic-0.2.1.tar.gz:

Publisher: wheels.yml on urschrei/rstar_geodetic

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file rtree_geodetic-0.2.1-cp310-abi3-win_amd64.whl.

File metadata

File hashes

Hashes for rtree_geodetic-0.2.1-cp310-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 6a261422ffbaf6b6def941c71ff06c51f57bf9c49159a57dab776b8bb86f6227
MD5 f89b974b958feadb1f0978193451ade2
BLAKE2b-256 0a73170adfbc270db39e951ba7142fc174462b59a167ccbff6f48256e5659667

See more details on using hashes here.

Provenance

The following attestation bundles were made for rtree_geodetic-0.2.1-cp310-abi3-win_amd64.whl:

Publisher: wheels.yml on urschrei/rstar_geodetic

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file rtree_geodetic-0.2.1-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for rtree_geodetic-0.2.1-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 3abdd11d0fe0d43f22bc4c9080a189ca29db40ad4ac6136d719b93d6397833ba
MD5 044c328009d80750a3f5b4401cf4c859
BLAKE2b-256 ee121d6439061face3d3059f1091720e6f2eebe20ecc9e318618ec5d1bcf0f23

See more details on using hashes here.

Provenance

The following attestation bundles were made for rtree_geodetic-0.2.1-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: wheels.yml on urschrei/rstar_geodetic

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file rtree_geodetic-0.2.1-cp310-abi3-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for rtree_geodetic-0.2.1-cp310-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 6eebfcb91f2f7f64694c1bed8772803e710f4437529022a34a8cea2859b30586
MD5 411f57652b055bb93f6e2ff9e1bd970d
BLAKE2b-256 b2d61d180de1d25f21bcdc8facf2ba5b37607849310dae5f8aede75c2765610a

See more details on using hashes here.

Provenance

The following attestation bundles were made for rtree_geodetic-0.2.1-cp310-abi3-macosx_11_0_arm64.whl:

Publisher: wheels.yml on urschrei/rstar_geodetic

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

0.2.1 This release

4 files

0.2.0

4 files

0.1.0

4 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page