Distance Calculator API: Complete Developer Guide

Need to calculate distances between two geographic points? This guide covers everything about distance calculation via API, including the Haversine formula, accuracy considerations, and implementation examples in multiple programming languages.

What is the Haversine Formula?

The Haversine formula calculates the great-circle distance between two points on a sphere given their latitudes and longitudes. It accounts for the Earth's curvature, providing accurate distances for any two points on the planet.

Example: New York (40.7128, -74.0060) to London (51.5074, -0.1278) = 5,570 km

How Distance Calculation Works

The calculation process:

Input Coordinates

Latitude and longitude for both points in decimal degrees.

Great Circle Distance

The shortest distance between two points on a sphere, following the surface.

Unit Conversion

Results can be returned in kilometers, miles, or nautical miles.

Using the Distance Calculator API

TinyFn provides a simple endpoint to calculate distances:

GET https://api.tinyfn.io/v1/geo/distance?lat1=40.7128&lon1=-74.0060&lat2=51.5074&lon2=-0.1278
Headers: X-API-Key: your-api-key

{
  "distance_km": 5570.22,
  "distance_miles": 3461.34,
  "distance_nm": 3007.95,
  "from": {
    "latitude": 40.7128,
    "longitude": -74.006
  },
  "to": {
    "latitude": 51.5074,
    "longitude": -0.1278
  }
}

Parameters

Code Examples

JavaScript / Node.js

const response = await fetch(
  'https://api.tinyfn.io/v1/geo/distance?lat1=40.7128&lon1=-74.0060&lat2=51.5074&lon2=-0.1278',
  { headers: { 'X-API-Key': 'your-api-key' } }
);
const result = await response.json();
console.log(`Distance: ${result.distance_km} km`);
// Distance: 5570.22 km

Python

import requests

response = requests.get(
    'https://api.tinyfn.io/v1/geo/distance',
    params={
        'lat1': 40.7128, 'lon1': -74.0060,
        'lat2': 51.5074, 'lon2': -0.1278
    },
    headers={'X-API-Key': 'your-api-key'}
)
result = response.json()
print(f"Distance: {result['distance_km']} km")
# Distance: 5570.22 km

cURL

curl "https://api.tinyfn.io/v1/geo/distance?lat1=40.7128&lon1=-74.0060&lat2=51.5074&lon2=-0.1278" \
  -H "X-API-Key: your-api-key"

Common Use Cases

• Store Locators: Find nearest stores to a customer's location
• Delivery Apps: Calculate delivery distances for pricing
• Travel Apps: Show distances between destinations
• Ride Sharing: Estimate trip distances and fares
• Logistics: Optimize routes and delivery schedules

Best Practices

1. Validate coordinates: Ensure lat/lon are within valid ranges
2. Choose appropriate units: Use km for international, miles for US audiences
3. Cache when possible: Cache distances for frequently calculated pairs
4. Consider routing: For driving distances, use routing APIs instead