Location-aware AI agents need to calculate distances, bearings, and coordinate transformations accurately. LLMs struggle with the trigonometry involved. This guide shows how to give your agents reliable geolocation tools via MCP.
Coordinate Calculations
Geographic coordinates come in multiple formats, and converting between them requires precision. TinyFn provides tools for all common coordinate operations.
Validate Coordinates
Before performing calculations, validate that coordinates are within valid ranges:
geo/validate-coordinates
{
"latitude": 40.7128,
"longitude": -74.0060
}{
"valid": true,
"latitude": 40.7128,
"longitude": -74.006,
"hemisphere": {
"latitude": "N",
"longitude": "W"
}
}DMS to Decimal Conversion
Convert degrees-minutes-seconds format to decimal degrees:
geo/dms-to-decimal
{
"degrees": 40,
"minutes": 42,
"seconds": 46.08,
"direction": "N"
}{
"decimal": 40.7128,
"dms": "40° 42' 46.08\" N"
}Decimal to DMS
Convert decimal degrees back to DMS format:
geo/decimal-to-dms
{
"decimal": -74.0060,
"type": "longitude"
}{
"degrees": 74,
"minutes": 0,
"seconds": 21.6,
"direction": "W",
"formatted": "74° 0' 21.6\" W"
}Distance and Bearing
Distance and bearing calculations require the Haversine formula and inverse trigonometric functions. These are impossible for LLMs to compute reliably.
Calculate Distance
geo/distance
{
"from": {
"latitude": 40.7128,
"longitude": -74.0060
},
"to": {
"latitude": 34.0522,
"longitude": -118.2437
},
"unit": "km"
}{
"distance": 3935.75,
"unit": "km",
"from": "New York area",
"to": "Los Angeles area",
"formula": "haversine"
}Calculate Bearing
Find the compass direction from one point to another:
geo/bearing
{
"from": {
"latitude": 40.7128,
"longitude": -74.0060
},
"to": {
"latitude": 34.0522,
"longitude": -118.2437
}
}{
"initialBearing": 273.45,
"finalBearing": 246.12,
"compassDirection": "W",
"description": "Head West"
}| Distance Unit | Code | Description |
|---|---|---|
| Kilometers | km |
Default, uses Earth radius 6371 km |
| Miles | mi |
Statute miles (5280 feet) |
| Nautical Miles | nm |
Used in aviation and maritime |
| Meters | m |
For short distances |
Midpoints and Destinations
Calculate Midpoint
Find the geographic midpoint between two coordinates:
geo/midpoint
{
"point1": {
"latitude": 40.7128,
"longitude": -74.0060
},
"point2": {
"latitude": 34.0522,
"longitude": -118.2437
}
}{
"midpoint": {
"latitude": 39.5123,
"longitude": -97.3826
},
"distanceFromPoint1": 1967.88,
"distanceFromPoint2": 1967.88,
"unit": "km"
}Destination Point
Find where you end up after traveling a distance along a bearing:
geo/destination
{
"start": {
"latitude": 51.5074,
"longitude": -0.1278
},
"bearing": 45,
"distance": 100,
"unit": "km"
}{
"destination": {
"latitude": 52.1396,
"longitude": 1.0342
},
"bearing": 45,
"distance": 100,
"unit": "km"
}Geocoding Accuracy
When working with geocoded addresses, precision matters. TinyFn helps validate and normalize coordinate data:
Coordinate Precision
Different precision levels serve different purposes:
| Decimal Places | Precision | Use Case |
|---|---|---|
| 1 | ~11 km | Country/region level |
| 2 | ~1.1 km | City/town level |
| 3 | ~110 m | Neighborhood level |
| 4 | ~11 m | Street level |
| 5 | ~1.1 m | Building level |
| 6 | ~0.11 m | Surveying precision |
Bounding Box
Calculate a bounding box around a center point:
geo/bounding-box
{
"center": {
"latitude": 40.7128,
"longitude": -74.0060
},
"radius": 10,
"unit": "km"
}{
"boundingBox": {
"north": 40.8027,
"south": 40.6229,
"east": -73.8887,
"west": -74.1233
},
"center": {
"latitude": 40.7128,
"longitude": -74.006
},
"radius": 10,
"unit": "km"
}Map-Based Agent Applications
Here are common use cases where AI agents need geolocation tools:
Store Locator Agent
async def find_nearest_stores(user_location, stores, max_distance_km=50):
"""Find stores within max_distance of user."""
nearby = []
for store in stores:
# Calculate distance using TinyFn
result = await tinyfn.call("geo/distance", {
"from": user_location,
"to": store["coordinates"],
"unit": "km"
})
if result["distance"] <= max_distance_km:
nearby.append({
"store": store,
"distance": result["distance"]
})
# Sort by distance
nearby.sort(key=lambda x: x["distance"])
return nearbyDelivery Route Assistant
async def estimate_delivery_info(origin, destination):
"""Calculate delivery distance and direction."""
# Get distance
distance = await tinyfn.call("geo/distance", {
"from": origin,
"to": destination,
"unit": "km"
})
# Get bearing for direction
bearing = await tinyfn.call("geo/bearing", {
"from": origin,
"to": destination
})
# Get midpoint for potential relay station
midpoint = await tinyfn.call("geo/midpoint", {
"point1": origin,
"point2": destination
})
return {
"total_distance_km": distance["distance"],
"direction": bearing["compassDirection"],
"initial_bearing": bearing["initialBearing"],
"relay_point": midpoint["midpoint"]
}Travel Planning Agent
async function planMultiStopRoute(stops) {
const legs = [];
for (let i = 0; i < stops.length - 1; i++) {
const from = stops[i];
const to = stops[i + 1];
// Calculate leg details
const [distance, bearing] = await Promise.all([
tinyfn.call("geo/distance", { from, to, unit: "km" }),
tinyfn.call("geo/bearing", { from, to })
]);
legs.push({
from: from.name,
to: to.name,
distance_km: distance.distance,
direction: bearing.compassDirection,
bearing: bearing.initialBearing
});
}
const totalDistance = legs.reduce((sum, leg) => sum + leg.distance_km, 0);
return {
legs,
totalDistance_km: totalDistance,
numberOfStops: stops.length
};
}Implementation Examples
MCP Configuration
{
"mcpServers": {
"tinyfn-geo": {
"url": "https://api.tinyfn.io/mcp/geo",
"headers": {
"X-API-Key": "your-api-key"
}
}
}
}Available Geo Tools
| Tool | Description |
|---|---|
geo/distance |
Calculate distance between two coordinates |
geo/bearing |
Calculate bearing between two points |
geo/midpoint |
Find the midpoint between two coordinates |
geo/destination |
Find destination given start, bearing, distance |
geo/bounding-box |
Calculate bounding box around a point |
geo/validate-coordinates |
Validate latitude/longitude values |
geo/dms-to-decimal |
Convert DMS to decimal degrees |
geo/decimal-to-dms |
Convert decimal to DMS format |
Build Location-Aware AI Agents
Give your agents accurate geolocation calculations they can trust.
Get Free API Key