geo

Geospatial basics: geohash encode/decode, great-circle distance and bearing, bounding boxes. Pure - no capabilities.

ecko get github.com/ecko-lang/geo
import geo

Pure computation: it declares no capabilities, so it cannot touch the network, the filesystem or the environment.

Version 0.39.0 - source - MIT.


encode(lat, lon, precision)

Returns the geohash of a point, precision characters long (1 to 22).

The scheme interleaves longitude and latitude bits, longitude first, and packs them five at a time into base 32. Each character narrows the cell, which is why a shared prefix means spatial proximity. A point exactly on a cell boundary goes to the lower cell.

errors: geo/bad_coordinate when a coordinate is out of range; bug/bad_argument when precision is not an Int from 1 to 22 or a coordinate is not a number.

geo.encode(57.64911, 10.40744, 11)   # "u4pruydqqvj"

decode_bbox(hash)

Returns the cell a geohash names, as { min_lat, max_lat, min_lon, max_lon }.

This is the honest answer: a geohash is an area, and decode only picks its centre. Upper-case hashes are accepted.

errors: geo/bad_geohash when the hash is empty or has a character outside the geohash alphabet; bug/bad_argument when it is not a string.

geo.decode_bbox("ezs42").min_lat   # 42.5830078125

decode(hash)

Returns { lat, lon }, the centre of the cell a geohash names.

Use decode_bbox when the size of the cell matters, which it usually does. Upper-case hashes are accepted.

errors: geo/bad_geohash when the hash is empty or has a character outside the geohash alphabet; bug/bad_argument when it is not a string.

geo.decode("ezs42")   # {lat: 42.60498046875, lon: -5.60302734375}

distance(lat1, lon1, lat2, lon2)

Returns the great-circle distance between two points in metres, by the haversine formula.

Haversine rather than the law of cosines because it stays accurate for small distances, where the cosine form loses precision to floating point.

errors: geo/bad_coordinate when a coordinate is out of range; bug/bad_argument when one is not a number.

geo.distance(0.0, 0.0, 0.0, 1.0)   # 111195.0802335329

km(lat1, lon1, lat2, lon2)

Returns the great-circle distance between two points in kilometres.

errors: geo/bad_coordinate when a coordinate is out of range; bug/bad_argument when one is not a number.

geo.km(51.5074, -0.1278, 48.8566, 2.3522)   # 343.55653488088325 - London to Paris

bearing(lat1, lon1, lat2, lon2)

Returns the initial bearing from the first point to the second, in degrees clockwise from north (0 to 360).

"Initial" because a great-circle course changes heading as you travel it.

errors: geo/bad_coordinate when a coordinate is out of range; bug/bad_argument when one is not a number.

geo.bearing(0.0, 0.0, 0.0, 10.0)   # 90

destination(lat, lon, bearing_deg, metres)

Returns { lat, lon }, where you arrive travelling metres from a point on a bearing in degrees clockwise from north.

errors: geo/bad_coordinate when a coordinate is out of range; bug/bad_argument when an argument is not a number.

geo.destination(51.5074, -0.1278, 90.0, 100000.0)

bbox(lat, lon, metres)

Returns a box { min_lat, max_lat, min_lon, max_lon } that contains every point within metres of the centre.

The box encloses the circle, so it includes corners further away than the radius: use it as a cheap first filter, then confirm with distance. When the circle crosses the antimeridian, min_lon is greater than max_lon (the box runs east from min_lon across 180 to max_lon, as in GeoJSON); within and center understand that. When it reaches a pole, the box spans every longitude.

errors: geo/bad_coordinate when a coordinate is out of range; bug/bad_argument when metres is negative or not a number.

geo.bbox(51.5074, -0.1278, 5000.0)

within(lat, lon, box)

Returns true when a point is inside a box; edges count as inside.

A box whose min_lon is greater than its max_lon crosses the antimeridian, and is read that way.

errors: bug/bad_argument when box is not a box or a coordinate is not a number.

geo.within(51.5, -0.12, geo.bbox(51.5074, -0.1278, 5000.0))   # true

center(box)

Returns { lat, lon }, the centre of a box, including one that crosses the antimeridian.

errors: bug/bad_argument when box is not a box.

geo.center({ min_lat: 0.0, max_lat: 10.0, min_lon: 20.0, max_lon: 30.0 })   # {lat: 5, lon: 25}