distancefyi

Pure TypeScript distance engine for developers. Compute Haversine great-circle distance, initial bearing, geographic midpoint, great-circle arc points, travel time estimates (flight, drive, walk), and unit conversions between km/miles/nautical miles -- all with zero dependencies.

Try the interactive tools at distancefyi.com -- distance calculator, travel time estimator, and city-to-city comparisons.

Table of Contents

• Install
• Quick Start
• What You Can Do
  • Understanding Great-Circle Distance
  • Bearing & Compass Direction
  • Midpoint & Great Circle Arc
  • Travel Time Estimates
• API Reference
• TypeScript Types
• Features
• Learn More About Distance
• Also Available for Python
• FYIPedia Developer Tools
• License

Install

npm install distancefyi

Works in Node.js, Deno, Bun, and browsers (ESM).

Quick Start

import { computeDistance, haversineDistance, formatDistance, formatDuration } from "distancefyi";

// Full distance computation between Seoul and Tokyo
const result = computeDistance(37.5665, 126.978, 35.6762, 139.6503);
console.log(result.distanceKm);          // 1159
console.log(result.distanceMiles);       // 720
console.log(result.bearingDegrees);      // 91.2
console.log(result.compassDirection);    // "E"
console.log(result.flightTimeMinutes);   // 123
console.log(result.driveTimeMinutes);    // 0 (cross-ocean)

// Simple Haversine distance
const km = haversineDistance(40.7128, -74.006, 51.5074, -0.1278);
console.log(formatDistance(km));          // "5,570 km"
console.log(formatDuration(420));        // "7h"

What You Can Do

Understanding Great-Circle Distance

The Haversine formula calculates the shortest path over Earth's surface. Unlike Euclidean distance, it accounts for Earth's curvature using spherical trigonometry.

Given two points with latitudes and longitudes in radians, the formula computes:

a = sin²(dlat/2) + cos(lat1) * cos(lat2) * sin²(dlon/2)
c = 2 * atan2(sqrt(a), sqrt(1-a))
distance = R * c

where R is Earth's mean radius (6,371.0088 km, WGS84). This gives accuracy within 0.5% for most practical distances. The implementation uses Math.atan2 for numerical stability near antipodal points.

Learn more: Distance Calculator · Haversine Formula · WGS84 Ellipsoid

Bearing & Compass Direction

The initial bearing (also called forward azimuth) is the compass direction you would need to travel in a straight line from point A to point B. It is measured in degrees clockwise from true north (0-360). The 16-point compass rose divides the circle into directions like N, NNE, NE, ENE, E, etc.

import { bearing, compassDirection, compassDirectionFull } from "distancefyi";

// Initial bearing from New York to London
const brng = bearing(40.7128, -74.006, 51.5074, -0.1278);
console.log(brng);                      // 51.2 (degrees from north)
console.log(compassDirection(brng));     // "NE"
console.log(compassDirectionFull(brng)); // "northeast"

Learn more: Compass Direction Guide · Bearing Calculator

Midpoint & Great Circle Arc

The geographic midpoint between two locations is not simply the average of their coordinates -- it must account for Earth's curvature. The midpoint calculation converts to Cartesian coordinates, averages them, and converts back. Great circle arc points are intermediate coordinates along the shortest surface path, useful for rendering flight paths on maps.

import { midpoint, greatCirclePoints, antipodalPoint } from "distancefyi";

// Geographic midpoint between two cities
const [midLat, midLon] = midpoint(40.7128, -74.006, 51.5074, -0.1278);
console.log(midLat, midLon);  // 50.50164, -36.04498

// Generate points along the great circle for map rendering
const arcPoints = greatCirclePoints(40.7128, -74.006, 51.5074, -0.1278, 20);
console.log(arcPoints.length);  // 21

// Antipodal point (opposite side of Earth)
const [antiLat, antiLon] = antipodalPoint(40.7128, -74.006);
console.log(antiLat, antiLon);  // -40.7128, 105.994

Learn more: Great Circle Paths · Antipodal Points

Travel Time Estimates

Estimate travel times for flights, driving, and walking based on distance. Flight time uses variable speed bands (shorter flights have lower average speeds due to takeoff/landing overhead). Drive time applies a 1.3x road distance factor to account for roads not following straight lines. Walking uses a constant 5 km/h speed with a 100 km maximum.

| Mode | Speed Model | Overhead | Max Distance | |------|------------|----------|-------------| | Flight | Variable: 500-900 km/h by distance band | +30 min (taxi, takeoff, landing) | Unlimited | | Drive | 60 km/h avg + 1.3x road factor | None | Same continent only | | Walk | 5 km/h constant | None | 100 km |

import { estimateFlightTime, estimateDriveTime, estimateWalkTime, formatDuration } from "distancefyi";

// Variable speed by distance band + 30-min overhead
console.log(formatDuration(estimateFlightTime(1000)));   // "1h 50m"
console.log(formatDuration(estimateFlightTime(10000)));  // "12h 36m"

// Drive time with 1.3x road distance factor
console.log(formatDuration(estimateDriveTime(500)));     // "8h 40m"
console.log(estimateDriveTime(500, false));              // 0 (cross-ocean)

// Walking at 5 km/h (max 100 km)
console.log(formatDuration(estimateWalkTime(10)));       // "2h"
console.log(estimateWalkTime(200));                      // 0 (too far)

Learn more: Flight Time Calculator · Distance Calculator

API Reference

Core Distance

| Function | Description | |----------|-------------| | haversineDistance(lat1, lon1, lat2, lon2) -> number | Great-circle distance in km (Haversine formula) | | computeDistance(lat1, lon1, lat2, lon2, sameContinent?) -> DistanceResult | Full computation: distance, bearing, midpoint, travel times |

Bearing & Direction

| Function | Description | |----------|-------------| | bearing(lat1, lon1, lat2, lon2) -> number | Initial bearing in degrees (0-360) | | compassDirection(degrees) -> string | 16-point compass abbreviation (e.g., "NE", "SSW") | | compassDirectionFull(degrees) -> string | Full compass name (e.g., "northeast", "south-southwest") |

Midpoint & Great Circle

| Function | Description | |----------|-------------| | midpoint(lat1, lon1, lat2, lon2) -> [number, number] | Geographic midpoint [lat, lon] | | greatCirclePoints(lat1, lon1, lat2, lon2, numPoints?) -> [number, number][] | Points along the great circle arc | | antipodalPoint(lat, lon) -> [number, number] | Point on the opposite side of Earth |

Travel Time Estimates

| Function | Description | |----------|-------------| | estimateFlightTime(distanceKm) -> number | Flight time in minutes (variable speed + 30min overhead) | | estimateDriveTime(distanceKm, sameContinent?) -> number | Drive time in minutes (1.3x road factor) | | estimateWalkTime(distanceKm) -> number | Walk time in minutes (5 km/h, max 100 km) |

Unit Conversion & Formatting

| Function | Description | |----------|-------------| | kmToMiles(km) -> number | Kilometers to miles | | kmToNauticalMiles(km) -> number | Kilometers to nautical miles | | milesToKm(miles) -> number | Miles to kilometers | | formatDistance(km) -> string | Format with thousands separator (e.g., "12,345 km") | | formatDuration(minutes) -> string | Human-readable duration (e.g., "2h 30m", "3d 5h") |

TypeScript Types

import type { DistanceResult } from "distancefyi";

Features

• Haversine formula: Great-circle distance using WGS84 mean radius (6,371.0088 km)
• 16-point compass: Bearing to compass direction (N, NNE, NE, ENE, E, ...)
• Geographic midpoint: True geodesic midpoint between two coordinates
• Great circle arc: Generate intermediate points for map rendering
• Travel time estimates: Flight (variable speed bands), drive (road factor), walk (5 km/h)
• Unit conversion: km, miles, and nautical miles
• Human-readable formatting: Distance with thousands separators, duration as "2h 30m"
• Zero dependencies: Pure TypeScript, no runtime deps
• Type-safe: Full TypeScript with strict mode
• Tree-shakeable: ESM with named exports
• Fast: All computations under 1ms

Learn More About Distance

• Tools: Distance Calculator · Flight Time
• Browse: Cities · Countries
• API: REST API Docs · OpenAPI Spec
• Python: PyPI Package

Also Available for Python

pip install distancefyi

See the Python package on PyPI.

FYIPedia Developer Tools

Part of the FYIPedia open-source developer tools ecosystem.

| Package | PyPI | npm | Description | |---------|------|-----|-------------| | colorfyi | PyPI | npm | Color conversion, WCAG contrast, harmonies -- colorfyi.com | | emojifyi | PyPI | npm | Emoji encoding & metadata for 3,953 emojis -- emojifyi.com | | symbolfyi | PyPI | npm | Symbol encoding in 11 formats -- symbolfyi.com | | unicodefyi | PyPI | npm | Unicode lookup with 17 encodings -- unicodefyi.com | | fontfyi | PyPI | npm | Google Fonts metadata & CSS -- fontfyi.com | | distancefyi | PyPI | npm | Haversine distance & travel times -- distancefyi.com | | timefyi | PyPI | npm | Timezone ops & business hours -- timefyi.com | | namefyi | PyPI | npm | Korean romanization & Five Elements -- namefyi.com | | unitfyi | PyPI | npm | Unit conversion, 220 units -- unitfyi.com | | holidayfyi | PyPI | npm | Holiday dates & Easter calculation -- holidayfyi.com | | cocktailfyi | PyPI | -- | Cocktail ABV, calories, flavor -- cocktailfyi.com | | fyipedia | PyPI | -- | Unified CLI: fyi color info FF6B35 -- fyipedia.com | | fyipedia-mcp | PyPI | -- | Unified MCP hub for AI assistants -- fyipedia.com |

License

MIT