Docs / Coordinates and distances

Coordinates and distances

The most common error in geographic code is not in any formula but in the order of two numbers. Most people and most mapping sites write latitude first; GeoJSON, many GIS tools and a lot of APIs write longitude first. Swap them and a point in Madrid lands in the Indian Ocean off the coast of Kenya, and nothing complains. Every endpoint here takes latitude first, and a pair whose first number cannot be a latitude is refused with a hint about the order rather than silently accepted.

The second choice is the shape of the Earth. The haversine formula treats the Earth as a sphere and is off by up to about half a percent, which is several kilometres on an intercontinental distance and enough to matter for aviation, surveying or any comparison with published figures. Distances, bearings and destinations here are solved on the WGS84 ellipsoid with Karney's method, and the spherical estimate is shown alongside for comparison.

Format conversions have quieter traps. A value in degrees, minutes and seconds carries its hemisphere as a letter, and careless parsing loses the sign, putting a western longitude in the east. A geohash identifies a cell, not a point, so the cell size belongs with it. UTM and MGRS divide the globe into zones with exceptions around Norway and Svalbard, and the same place near a zone boundary can be written in two valid ways.

Nothing is geocoded: place names are not turned into coordinates, or coordinates into addresses.

Every endpoint in this group

/geo/distance?from=&to=&[unit=]

Distance between two points on the WGS84 ellipsoid (Karney), plus spherical estimate

from: latitude,longitude; to: latitude,longitude; unit (optional): m, km, mi, nmi or ft

curl "https://agent-helper.org/geo/distance?from=55.7558,37.6173&to=40.7128,-74.0060"

/geo/bearing?from=&to=

Initial and final bearing (azimuth) from one point to another

from: latitude,longitude; to: latitude,longitude

curl "https://agent-helper.org/geo/bearing?from=51.5074,-0.1278&to=48.8566,2.3522"

/geo/destination?from=&bearing=&distance=&[unit=]

Point reached from a start point, bearing and distance (direct geodesic problem)

from: latitude,longitude; bearing: degrees clockwise from true north; distance: distance; unit (optional): m, km, mi, nmi or ft

curl "https://agent-helper.org/geo/destination?from=55.7558,37.6173&bearing=90&distance=100"

/geo/midpoint?from=&to=

Midpoint of the geodesic between two points

from: latitude,longitude; to: latitude,longitude

curl "https://agent-helper.org/geo/midpoint?from=55.7558,37.6173&to=59.9343,30.3351"

/geo/dms?point=

Decimal degrees to degrees, minutes, seconds

point: latitude,longitude in decimal degrees

curl "https://agent-helper.org/geo/dms?point=55.7558,37.6173"

/geo/decimal?lat=&lon=

Degrees-minutes-seconds text to decimal degrees

lat: latitude, e.g. 55°45'20.9"N; lon: longitude, e.g. 37°37'02.3"E

curl "https://agent-helper.org/geo/decimal?lat=55%C2%B045'20.9%22N&lon=37%C2%B037'02.3%22E"

/geo/geohash?point=&[precision=]

Encode a point as a geohash

point: latitude,longitude; precision (optional): characters, 1-12

curl "https://agent-helper.org/geo/geohash?point=57.64911,10.40744&precision=11"

/geo/geohash/{hash}

Decode a geohash to its cell centre and size

hash: geohash

curl "https://agent-helper.org/geo/geohash/u4pruydqqvj"

/geo/utm?point=

Latitude/longitude to UTM zone, easting, northing (WGS84)

point: latitude,longitude

curl "https://agent-helper.org/geo/utm?point=55.7558,37.6173"

/geo/mgrs?point=&[precision=]

Latitude/longitude to an MGRS grid reference

point: latitude,longitude; precision (optional): digits per axis 0-5 (5 = 1 m)

curl "https://agent-helper.org/geo/mgrs?point=55.7558,37.6173"

/geo/mgrs/{code}

MGRS grid reference to latitude/longitude (south-west corner of the square)

code: MGRS reference

curl "https://agent-helper.org/geo/mgrs/37UDB1322479766"