Distance & Bearing

Calculate great-circle distance (shortest path between two points on a sphere — not a straight line on a flat map), initial bearing (compass direction from origin to destination in degrees true), eight-point cardinal direction, and geographic midpoint between two points. Each side can be an airport code or raw WGS-84 coordinates — mixed mode is supported.

Use for route-preview cards, fuel calculators, and range-ring overlays without maintaining your own Haversine implementation.

Request

Requirements

Auth

x-api-key on every request (direct subscription). Learn more →

GEThttps://data.skylinkapi.com/v3/distance

Parameter	Type	Required	Default	Description
`from_icao`	string	Conditionally	-	Origin airport ICAO or IATA code
`to_icao`	string	Conditionally	-	Destination airport ICAO or IATA code
`from_lat`	number	Conditionally	-	Origin latitude (`-90` to `90`)
`from_lon`	number	Conditionally	-	Origin longitude (`-180` to `180`)
`to_lat`	number	Conditionally	-	Destination latitude (`-90` to `90`)
`to_lon`	number	Conditionally	-	Destination longitude (`-180` to `180`)
`unit`	string	No	`nm`	Preferred display unit (`nm`, `km`, `mi`)

Provide each side as either a code pair or a coordinate pair:

Mode	Example
Airport → airport	`from_icao=KJFK&to_icao=EGLL`
Coordinate → airport	`from_lat=40.6413&from_lon=-73.7781&to_icao=EGLL`
Coordinate → coordinate	`from_lat=40.64&from_lon=-73.78&to_lat=51.47&to_lon=-0.46`

Response

{
  "from": "KJFK",
  "to": "EGLL",
  "distance_nm": 2991.61,
  "distance_km": 5539.91,
  "distance_mi": 3442.19,
  "bearing_deg": 51.35,
  "cardinal": "NE",
  "midpoint_lat": 52.216,
  "midpoint_lon": -41.306
}

Field	Type	Required	Description
`from`	string	Yes	Resolved origin identifier
`to`	string	Yes	Resolved destination identifier
`distance_nm`	number	Yes	Distance in nautical miles (1 NM ≈ 1.852 km — standard aviation unit)
`distance_km`	number	Yes	Distance in kilometres
`distance_mi`	number	Yes	Distance in statute miles
`bearing_deg`	number	Yes	Initial true bearing (0–360)
`cardinal`	string	Yes	Eight-point direction (`N`, `NE`, `E`, …) derived from bearing
`midpoint_lat`	number	Yes	Geographic midpoint latitude
`midpoint_lon`	number	Yes	Geographic midpoint longitude

All three distance units are always returned regardless of the unit parameter. Use unit only as a display preference.

Client types

"""Distance endpoint response models for /distance."""from __future__ import annotationsfrom dataclasses import dataclass@dataclassclass DistanceRequest:    from_icao: str | None = None    to_icao: str | None = None    from_lat: float | None = None    from_lon: float | None = None    to_lat: float | None = None    to_lon: float | None = None    unit: str | None = None@dataclassclass DistanceResponse:    from_: str    to: str    distance_nm: float    distance_km: float    distance_mi: float    bearing_deg: float    cardinal: str    midpoint_lat: float    midpoint_lon: float

Integration

Compute route geometry for a preview card with explicit timeout handling.

import osimport requestsBASE = "https://data.skylinkapi.com/v3"HEADERS = {    "x-api-key": os.getenv("SKYLINK_API_KEY", "YOUR_API_KEY")}def fetch_distance(from_icao: str, to_icao: str) -> dict:    """Fetch great-circle distance and initial bearing between two airports."""    r = requests.get(        f"{BASE}/distance",        headers=HEADERS,        params={"from_icao": from_icao, "to_icao": to_icao},        timeout=(10, 15),    )    r.raise_for_status()    return r.json()if __name__ == "__main__":    import json    data = fetch_distance("KJFK", "KLAX")    print(json.dumps(data, indent=2, default=str))

Implementation notes

Input validation. Validate latitude/longitude bounds client-side to avoid avoidable 422 responses.

Cardinal direction. cardinal reflects initial bearing only — not wind or published airway routing.

Route resolution. For callsign → origin/destination pairs, use Routes (v3.1). For ML-predicted block time, see Flight Time.

Error responses

For shared platform errors, see Error Handling. Endpoint-specific:

422 - invalid point definition

{
  "detail": [
    {
      "type": "value_error",
      "loc": ["query", "from_lat"],
      "msg": "from_lat must be between -90 and 90"
    }
  ]
}

Authorization

x-api-key<token>

Your SkyLink licence key, for keys bought direct from skylinkapi.com.

In: header

Query Parameters

from_icao?string

Origin airport ICAO or IATA code (e.g. KJFK, JFK)

to_icao?string

Destination airport ICAO or IATA code (e.g. EGLL, LHR)

from_lat?number

Origin latitude (-90 to 90)

Range-90 <= value <= 90

from_lon?number

Origin longitude (-180 to 180)

Range-180 <= value <= 180

to_lat?number

Destination latitude (-90 to 90)

Range-90 <= value <= 90

to_lon?number

Destination longitude (-180 to 180)

Range-180 <= value <= 180

unit?string

Distance unit: nm (nautical miles), km, or mi

Default"nm"

Value in"nm" | "km" | "mi"

Response Body

`application/json`

curl -X GET "https://data.skylinkapi.com/v3/distance"

{
  "from_point": {
    "latitude": 40.639751,
    "longitude": -73.778925,
    "icao_code": "KJFK",
    "iata_code": "JFK",
    "name": "John F Kennedy International Airport"
  },
  "to_point": {
    "latitude": 51.4706,
    "longitude": -0.461941,
    "icao_code": "EGLL",
    "iata_code": "LHR",
    "name": "London Heathrow Airport"
  },
  "distance": 2991.01,
  "unit": "nm",
  "bearing": 51.35,
  "bearing_cardinal": "NE",
  "midpoint": {
    "latitude": 52.216674,
    "longitude": -41.302671
  }
}

Empty

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "input": null,
      "ctx": {}
    }
  ]
}

Related: Airports · Flight Time · Flight Briefing

Request

Response

Client types

Integration

Implementation notes

Error responses

422 - invalid point definition

Authorization

Query Parameters

Response Body

200application/json

400

404

422application/json

On this page

`application/json`

`application/json`