POST AI agent ready /v1/geo/distance

Distance Calculator API - Free Haversine Formula

Provide two latitude/longitude pairs and receive the distance between them calculated using the Haversine formula. Supports kilometers, miles, and nautical miles. Accurate for any two points on Earth. No external service calls; the calculation runs entirely on the server.

Endpoint

Code examples

curl -X POST https://api.botoi.com/v1/geo/distance \
  -H "Content-Type: application/json" \
  -d '{"from":{"lat":40.7128,"lng":-74.006},"to":{"lat":51.5074,"lng":-0.1278},"unit":"km"}'

When to use this API

Sort nearby stores or restaurants by distance from the user

Calculate the distance from the user's coordinates to each location in your database. Sort by the result to show the closest options first. Runs server-side so you don't need a Google Maps API key.

Validate delivery radius for an e-commerce checkout

Before confirming an order, calculate the distance between your warehouse and the delivery address. Reject or apply a surcharge if the distance exceeds your delivery zone.

Build a travel distance tracker for fitness or logistics apps

Send sequential GPS waypoints and sum the distances to compute total trip length. Works for running routes, fleet tracking, or cycling apps.

Frequently asked questions

How accurate is the Haversine formula?

The Haversine formula assumes a perfect sphere and is accurate to within about 0.3% for most distances on Earth. For sub-meter precision, use the Vincenty formula, which accounts for Earth's ellipsoidal shape.

What coordinate system does this endpoint expect?

WGS84 decimal degrees. Latitude ranges from -90 to 90 (south to north). Longitude ranges from -180 to 180 (west to east). This is the same system used by GPS devices and Google Maps.

Can I calculate distances for more than two points?

This endpoint handles one pair of points per request. For multi-point routes, call the endpoint for each consecutive pair and sum the distances.

What is the difference between km, mi, and nm?

km = kilometers (1 km = 1000 meters). mi = statute miles (1 mi = 1.609 km). nm = nautical miles (1 nm = 1.852 km). Nautical miles are standard in aviation and maritime navigation.

Does this endpoint call an external mapping service?

No. The Haversine calculation runs entirely on the server with no external API calls. This means zero additional latency and no third-party rate limits.

Get your API key

Free tier includes 5 requests per minute with no credit card required. Upgrade for higher limits.