# Haversine Distance Calculator

> Computes the great-circle (as-the-crow-flies) distance between two points on a spherical Earth with the haversine formula, in kilometres, miles and nautical miles, together with the initial bearing, compass direction and the midpoint of the route.

- Calculator id: `haversine-distance` · Category: Time & Geography (`time`) · Tool name: `calculate_haversine_distance`
- Canonical page: https://tttkmbb.com/time/haversine-distance · This document: https://tttkmbb.com/time/haversine-distance.md · JSON definition: https://tttkmbb.com/time/haversine-distance.json

## Purpose

Computes the great-circle (as-the-crow-flies) distance between two points on a spherical Earth with the haversine formula, in kilometres, miles and nautical miles, together with the initial bearing, compass direction and the midpoint of the route.

**Use when:** You need the straight-line distance between two GPS coordinates or cities, e.g. for flight distance, range checks or geofencing.

**Do not use when:** You need road distance, or ellipsoidal accuracy better than about 0.5 % (use a geodesic method such as Vincenty or Karney on WGS-84); for bearings and compass points use compass-bearing.

## Input

| Parameter | Type | Unit | Required | Description |
| --- | --- | --- | --- | --- |
| `lat1` | number | ° | required | Latitude of point 1 in decimal degrees (north positive, south negative). (min -90, max 90) |
| `lon1` | number | ° | required | Longitude of point 1 in decimal degrees (east positive, west negative). (min -180, max 180) |
| `lat2` | number | ° | required | Latitude of point 2 in decimal degrees (north positive, south negative). (min -90, max 90) |
| `lon2` | number | ° | required | Longitude of point 2 in decimal degrees (east positive, west negative). (min -180, max 180) |

## Output

| Field | Type | Unit | Description |
| --- | --- | --- | --- |
| `distance_km` | number | km | Great-circle distance on a sphere of radius 6,371.0088 km. |
| `distance_miles` | number | mi | Same distance in statute miles (1 mi = 1.609344 km). |
| `distance_nautical_miles` | number | nmi | Same distance in nautical miles (1 nmi = 1.852 km). |
| `central_angle_degrees` | number | ° | Angle subtended at the Earth's centre. |
| `initial_bearing_degrees` | number | ° | Forward azimuth at point 1, clockwise from true north (0–360). |
| `compass_direction` | string |  | 16-point compass direction of the initial bearing. |
| `midpoint_lat` | number | ° | Latitude of the great-circle midpoint. |
| `midpoint_lon` | number | ° | Longitude of the great-circle midpoint. |

## Formula

`a = sin²(Δφ/2) + cos φ1 · cos φ2 · sin²(Δλ/2); c = 2 · atan2(√a, √(1−a)); d = R · c with R = 6371.0088 km; θ = atan2(sin Δλ · cos φ2, cos φ1 · sin φ2 − sin φ1 · cos φ2 · cos Δλ)`

Spherical model with the IUGG mean Earth radius; real distances on the WGS-84 ellipsoid differ by up to about 0.3–0.5 %. The bearing is the initial heading; on long routes it changes continuously along the great circle.

## Data Sources

- Veness C – Calculate distance, bearing and more between latitude/longitude points (Movable Type Scripts) — https://www.movable-type.co.uk/scripts/latlong.html (reference, retrieved 2026-09-24)
- Haversine formula (Wikipedia) — https://en.wikipedia.org/wiki/Haversine_formula (reference, retrieved 2026-09-24)
- Earth radius – IUGG mean radius R1 = 6,371.0088 km (Wikipedia) — https://en.wikipedia.org/wiki/Earth_radius (reference, retrieved 2026-09-24)

Data freshness: `static`. Deterministic formula with fixed constants; results never go stale. Inputs supplied by the caller determine the output.

## API

- `GET https://tttkmbb.com/api/v1/calculate/haversine-distance?lat1=…&lon1=…&lat2=…&lon2=…`
- `POST https://tttkmbb.com/api/v1/calculate/haversine-distance` with JSON body `{"inputs": {…}}`
- Response: unified envelope (`success`, `request`, `result.values`, `result.units`, `sources`, `freshness`, `timestamp`, `next_actions`, `links`); see https://tttkmbb.com/docs/response-format.md
- Schema: https://tttkmbb.com/api/v1/calculators/haversine-distance · OpenAPI operationId `calculate_haversine_distance` in https://tttkmbb.com/openapi.json
- Authentication: none. Rate limit: fair use, see https://tttkmbb.com/docs/rate-limits.md.

## MCP

- Server: `https://tttkmbb.com/mcp` (Streamable HTTP, JSON-RPC 2.0, no auth)
- Tool: `calculate_haversine_distance` (dedicated) or `run_calculator` with `{"calculator_id": "haversine-distance", "inputs": {…}}`

## Example

- Sydney → Tokyo: inputs `{"lat1":-33.8688,"lon1":151.2093,"lat2":35.6762,"lon2":139.6503}` → `{"distance_km":7825.83,"distance_miles":4862.74,"distance_nautical_miles":4225.61,"central_angle_degrees":70.3793,"initial_bearing_degrees":350.05,"compass_direction":"N (north)","midpoint_lat":0.9083,"midpoint_lon":145.4933}`
- Movable Type example: 50°03′59″N 5°42′53″W → 58°38′38″N 3°04′12″W: inputs `{"lat1":50.06639,"lon1":-5.71472,"lat2":58.64389,"lon2":-3.07}` → `{"distance_km":968.85,"distance_miles":602.02,"initial_bearing_degrees":9.12,"midpoint_lat":54.3623,"midpoint_lon":-4.5307}`

```
GET https://tttkmbb.com/api/v1/calculate/haversine-distance?lat1=-33.8688&lon1=151.2093&lat2=35.6762&lon2=139.6503
```

## Limitations

You need road distance, or ellipsoidal accuracy better than about 0.5 % (use a geodesic method such as Vincenty or Karney on WGS-84); for bearings and compass points use compass-bearing. Spherical model with the IUGG mean Earth radius; real distances on the WGS-84 ellipsoid differ by up to about 0.3–0.5 %. The bearing is the initial heading; on long routes it changes continuously along the great circle. All values are computed from the formula above; no measurement or live data is involved.

## FAQ

**How accurate is the haversine formula?**

It is exact for a sphere and numerically stable for short distances. Because the Earth is an oblate ellipsoid, results differ from geodesic (Vincenty/Karney) distances by up to about 0.5 %, i.e. roughly 30 km on a 7,800 km flight.

**Which sign convention do the coordinates use?**

Decimal degrees: north and east positive, south and west negative. Use coordinate-converter to turn degrees-minutes-seconds into decimals first.

## Related

- [Compass Bearing Calculator](https://tttkmbb.com/time/compass-bearing.md) — Initial and final bearing with compass points for the same route.
- [Coordinate Converter](https://tttkmbb.com/time/coordinate-converter.md) — Convert DMS coordinates to the decimal degrees this calculator needs.
- [Length Converter](https://tttkmbb.com/conversion/length.md) — Convert the distance to other length units.