Pure Python distance engine for developers. Compute Haversine great-circle distances, initial bearings with 16-point compass directions, geographic midpoints, great circle arcs, antipodal points, and realistic travel time estimates -- all with zero dependencies.
Explore distances between world cities at distancefyi.com -- distance calculator, city-to-city routes, and travel time estimates.
- Install
- Quick Start
- Understanding Distance Calculation
- Navigation & Bearing
- Travel Time Estimates
- Command-Line Interface
- MCP Server (Claude, Cursor, Windsurf)
- REST API Client
- API Reference
- Features
- Learn More About Distance
- Utility FYI Family
- License
pip install distancefyi # Core engine (zero deps)
pip install "distancefyi[cli]" # + Command-line interface
pip install "distancefyi[mcp]" # + MCP server for AI assistants
pip install "distancefyi[api]" # + HTTP client for distancefyi.com API
pip install "distancefyi[all]" # Everythingfrom distancefyi import haversine_distance, bearing, midpoint, compute_distance
# Seoul to Tokyo
haversine_distance(37.5665, 126.978, 35.6762, 139.6503) # 1159 km
bearing(37.5665, 126.978, 35.6762, 139.6503) # 108.6 degrees
midpoint(37.5665, 126.978, 35.6762, 139.6503) # (36.82..., 133.36...)
# Full computation with travel times
result = compute_distance(37.5665, 126.978, 35.6762, 139.6503)
result.distance_km # 1159
result.distance_miles # 720
result.compass_direction # "ESE"
result.flight_time_minutes # 123The Haversine formula computes the great-circle distance between two points on a sphere. It uses the Earth's mean radius (R = 6,371 km) as a spherical approximation, which introduces a maximum error of about 0.3% compared to the true ellipsoidal distance. For most applications -- route planning, city-to-city comparisons, flight distance estimation -- this is more than sufficient.
| Distance Unit | Abbreviation | Relative to 1 km | Common Use |
|---|---|---|---|
| Kilometer | km | 1.0 | Worldwide standard |
| Mile (statute) | mi | 0.6214 | US, UK road distances |
| Nautical mile | nmi | 0.5400 | Aviation, maritime navigation |
| Meter | m | 1,000 | Walking, urban distances |
| Foot | ft | 3,280.84 | US/UK altitude, short distances |
from distancefyi import haversine_distance, km_to_miles, km_to_nautical_miles
# Great-circle distance between New York and London
km = haversine_distance(40.7128, -74.0060, 51.5074, -0.1278) # NYC to London
miles = km_to_miles(km) # 3,459 statute miles
nm = km_to_nautical_miles(km) # 3,005 nautical miles (used in aviation)For sub-meter precision (surveying, geodesy), you would need Vincenty's formula on the WGS84 ellipsoid, which accounts for the Earth's equatorial bulge. The Haversine formula treats the Earth as a perfect sphere, so it slightly underestimates distances near the equator and overestimates near the poles.
Learn more: Distance Calculator · Browse Cities · Browse Countries
The initial bearing (forward azimuth) is the compass direction you would face when starting a journey along the great-circle route. Unlike a rhumb line (constant compass bearing), a great-circle route's bearing changes continuously along the path -- this is why flight paths on a Mercator map appear curved.
| Compass Direction | Abbreviation | Degree Range |
|---|---|---|
| North | N | 348.75 -- 11.25 |
| North-Northeast | NNE | 11.25 -- 33.75 |
| Northeast | NE | 33.75 -- 56.25 |
| East-Northeast | ENE | 56.25 -- 78.75 |
| East | E | 78.75 -- 101.25 |
| East-Southeast | ESE | 101.25 -- 123.75 |
| Southeast | SE | 123.75 -- 146.25 |
| South-Southeast | SSE | 146.25 -- 168.75 |
| South | S | 168.75 -- 191.25 |
| South-Southwest | SSW | 191.25 -- 213.75 |
| Southwest | SW | 213.75 -- 236.25 |
| West-Southwest | WSW | 236.25 -- 258.75 |
| West | W | 258.75 -- 281.25 |
| West-Northwest | WNW | 281.25 -- 303.75 |
| Northwest | NW | 303.75 -- 326.25 |
| North-Northwest | NNW | 326.25 -- 348.75 |
from distancefyi import bearing, compass_direction, great_circle_points, antipodal_point
# Initial bearing from New York to London (great-circle route)
b = bearing(40.7128, -74.0060, 51.5074, -0.1278) # 51.2 degrees
compass_direction(b) # "NE" (Northeast)
# Generate waypoints along the great-circle arc for route visualization
points = great_circle_points(40.7128, -74.0060, 51.5074, -0.1278, num_points=10)
# Antipodal point -- diametrically opposite location on Earth
lat, lon = antipodal_point(40.7128, -74.0060) # (-40.7128, 105.994)The 16-point compass rose divides 360 degrees into directions: N, NNE, NE, ENE, E, ESE, SE, SSE, S, SSW, SW, WSW, W, WNW, NW, NNW. Each sector spans 22.5 degrees.
Learn more: Distance Calculator · City Routes
Travel time estimates use realistic speed models that account for acceleration, deceleration, rest stops, and real-world conditions rather than simple distance-over-speed division.
| Travel Mode | Average Speed | Includes | Best For |
|---|---|---|---|
| Flight | 850 km/h cruise | Taxi, climb, descent, approach | Distances > 300 km |
| Driving | 80 km/h average | Rest stops, speed variation | 50 -- 2,000 km |
| Walking | 5 km/h | Steady pace, no stops | < 30 km |
| Distance Band | Flight Time | Drive Time | Walk Time |
|---|---|---|---|
| 500 km | ~70 min | ~6 h | ~4 days |
| 1,000 km | ~110 min | ~12.5 h | ~8 days |
| 5,000 km | ~390 min | ~62.5 h | ~42 days |
| 10,000 km | ~740 min | ~125 h | ~83 days |
from distancefyi import estimate_flight_time, estimate_drive_time, estimate_walk_time
# Seoul to Tokyo distance in kilometers
km = 1159
# Realistic flight time with taxi, climb, cruise, and descent phases
estimate_flight_time(km) # ~123 minutes (cruising at 850 km/h)
# Driving time with average highway speed and rest stops
estimate_drive_time(km) # ~870 minutes (average 80 km/h)
# Walking time at a steady 5 km/h pace
estimate_walk_time(km) # ~13,908 minutesLearn more: Flight Time Calculator · City Distance Routes · Country Distances
pip install "distancefyi[cli]"
distancefyi calc --lat1 37.5665 --lon1 126.978 --lat2 35.6762 --lon2 139.6503
distancefyi bearing --lat1 37.57 --lon1 126.98 --lat2 35.68 --lon2 139.65
distancefyi midpoint --lat1 37.57 --lon1 126.98 --lat2 35.68 --lon2 139.65
distancefyi convert 100 km miAdd distance tools to any AI assistant that supports Model Context Protocol.
pip install "distancefyi[mcp]"Add to your claude_desktop_config.json:
{
"mcpServers": {
"distancefyi": {
"command": "python",
"args": ["-m", "distancefyi.mcp_server"]
}
}
}Available tools: calculate_distance, get_bearing, get_midpoint, get_flight_time, convert_distance
pip install "distancefyi[api]"from distancefyi.api import DistanceFYI
with DistanceFYI() as client:
result = client.distance("seoul", "tokyo")Full API documentation at distancefyi.com.
| Function | Description |
|---|---|
haversine_distance(lat1, lon1, lat2, lon2) -> int |
Great-circle distance in km |
compute_distance(lat1, lon1, lat2, lon2) -> DistanceResult |
Full computation with all metrics |
bearing(lat1, lon1, lat2, lon2) -> float |
Initial bearing in degrees (0-360) |
compass_direction(degrees) -> str |
16-point compass abbreviation (e.g., "NE") |
compass_direction_full(degrees) -> str |
Full compass name (e.g., "Northeast") |
| Function | Description |
|---|---|
midpoint(lat1, lon1, lat2, lon2) -> tuple[float, float] |
Geographic midpoint |
great_circle_points(lat1, lon1, lat2, lon2, num_points) -> list |
Waypoints along the arc |
antipodal_point(lat, lon) -> tuple[float, float] |
Diametrically opposite point |
| Function | Description |
|---|---|
estimate_flight_time(km) -> int |
Flight time in minutes |
estimate_drive_time(km) -> int |
Drive time in minutes |
estimate_walk_time(km) -> int |
Walk time in minutes |
| Function | Description |
|---|---|
km_to_miles(km) -> float |
Kilometers to miles |
km_to_nautical_miles(km) -> float |
Kilometers to nautical miles |
miles_to_km(miles) -> float |
Miles to kilometers |
format_distance(km) -> str |
Human-readable distance string |
format_duration(minutes) -> str |
Human-readable duration string |
- Haversine distance -- great-circle distance in km, miles, nautical miles
- Bearing -- initial bearing with 16-point compass direction
- Midpoint -- geographic midpoint between two coordinates
- Great circle arc -- generate waypoints along the shortest path
- Antipodal point -- diametrically opposite point on Earth
- Travel time estimates -- flight, drive, walk time with realistic models
- Unit conversion -- km, miles, nautical miles
- Formatting -- human-readable distance and duration strings
- CLI -- Rich terminal output with distance tables
- MCP server -- 5 tools for AI assistants (Claude, Cursor, Windsurf)
- REST API client -- httpx-based client for distancefyi.com API
- Zero dependencies -- core engine uses only
mathfrom stdlib - Type-safe -- full type annotations,
py.typedmarker (PEP 561)
- Tools: Distance Calculator · Flight Time Calculator
- Browse: Cities · Countries
- Guides: Glossary · Blog
- API: REST API Docs · OpenAPI Spec
Part of the FYIPedia open-source developer tools ecosystem — everyday developer reference and conversion tools.
| Package | PyPI | npm | Description |
|---|---|---|---|
| unitfyi | PyPI | npm | Unit conversion, 220 units -- unitfyi.com |
| timefyi | PyPI | npm | Timezone ops & business hours -- timefyi.com |
| holidayfyi | PyPI | npm | Holiday dates & Easter calculation -- holidayfyi.com |
| namefyi | PyPI | npm | Korean romanization & Five Elements -- namefyi.com |
| distancefyi | PyPI | npm | Haversine distance & travel times -- distancefyi.com |
MIT