Footstep is a routing API that adds terrain intelligence to every response. Send two coordinates and you get back directions, distance, duration, and a full elevation breakdown (ascent, descent, grade profiles, and a difficulty classification) in one call.
This guide walks you through your first request.
Get an API key
Sign up at console.footstep.ai and create an API key. Your key will look like sk_live_abc123.... Keep it safe, as it’s used to authenticate every request.
API keys are for server-side use only. Never expose them in frontend code, mobile apps, or anywhere a user could inspect network traffic.
Your first request
Every routing request needs at least two locations: a start and an end. Each location is a lat/lon pair. Here’s a route from King’s Cross to Tower Bridge in London:
curl -X POST https://api.footstep.ai/v1/routing/route \
-H "x-api-key: sk_live_your_key_here" \
-H "Content-Type: application/json" \
-d '{
"locations": [
{ "lat": 51.5322, "lon": -0.1240 },
{ "lat": 51.5055, "lon": -0.0754 }
]
}'
Understand the response
The response contains a route object with everything you need:
{
"route": {
"distance_m": 5765,
"duration_s": 812,
"terrain": {
"total_ascent_m": 12.4,
"total_descent_m": 8.1,
"max_elevation_m": 28,
"min_elevation_m": 5,
"avg_grade_percent": 1.2,
"max_grade_percent": 4.5,
"elevation_profile": [
{ "distance_m": 0, "elevation_m": 22 },
{ "distance_m": 500, "elevation_m": 18 },
{ "distance_m": 1000, "elevation_m": 15 }
],
"difficulty": "flat"
},
"legs": [
{
"distance_m": 5765,
"duration_s": 812,
"steps": [
{
"instruction": "Drive north on Midland Road.",
"distance_m": 120,
"duration_s": 15
}
]
}
]
}
}
| Field | What it tells you |
|---|
distance_m | Total route distance in meters |
duration_s | Estimated travel time in seconds |
terrain.total_ascent_m | Total climbing over the route in meters |
terrain.total_descent_m | Total descending over the route in meters |
terrain.elevation_profile | Array of distance/elevation points for charting |
terrain.difficulty | Overall classification: flat, rolling, hilly, or mountainous |
legs[].steps[] | Turn-by-turn directions with distance and time per manoeuvre |
All field names include their unit. distance_m is always meters, duration_s is always seconds, grade_percent is always a percentage. This is true regardless of the units parameter you send in the request.
Change transport mode
The default mode is auto (car). You can switch to walking, cycling, or other modes using the costing parameter:
{
"locations": [
{ "lat": 51.5322, "lon": -0.1240 },
{ "lat": 51.5055, "lon": -0.0754 }
],
"costing": "pedestrian"
}
| Mode | Use case |
|---|
auto | Car routing (default) |
pedestrian | Walking and hiking. Factors in terrain, avoids motorways |
bicycle | Cycling. Considers surface type and hill gradients |
bus | Bus routing |
truck | Truck routing. Respects vehicle dimensions and weight limits |
pedestrian route through hilly terrain will show significantly different difficulty and grade profiles compared to the same coordinates with auto.
By default, responses use the footstep format, which is compact JSON with encoded polyline geometry. If you’re working with mapping libraries or GIS tools, you can request GeoJSON instead:
{
"locations": [
{ "lat": 51.5322, "lon": -0.1240 },
{ "lat": 51.5055, "lon": -0.0754 }
],
"format": "geojson"
}
Next steps
