curl --request POST \
--url https://api.footstep.ai/v1/routing/route \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"locations": [
{
"lat": 51.5322,
"lon": -0.124
},
{
"lat": 51.5055,
"lon": -0.0754
}
]
}
'{
"route": {
"waypoints": [
{
"lat": 123,
"lon": 123,
"original_index": 123
}
],
"legs": [
{
"distance_meters": 123,
"duration_seconds": 123,
"shape": "<string>",
"steps": [
{
"type": "none",
"instruction": "<string>",
"street_names": [
"<string>"
],
"distance_meters": 123,
"duration_seconds": 123,
"begin_shape_index": 123,
"end_shape_index": 123,
"travel_mode": "<string>",
"flags": {
"toll": true,
"ferry": true,
"rough": true,
"gate": true,
"highway": true
},
"verbal_alert": "<string>",
"verbal_instruction": "<string>",
"bearing_before": 123,
"bearing_after": 123,
"roundabout_exit_count": 123,
"exit_sign": {
"exit_number": "<string>",
"exit_branch": "<string>",
"exit_toward": "<string>",
"exit_name": "<string>"
},
"lanes": [
{
"indications": [
"<string>"
],
"valid": true,
"active": true
}
]
}
],
"terrain": {
"total_ascent_meters": 123,
"total_descent_meters": 123,
"max_elevation_meters": 123,
"min_elevation_meters": 123,
"avg_grade_percent": 123,
"max_grade_percent": 123,
"elevation_profile": [
{
"distance_meters": 123,
"elevation_meters": 123
}
],
"difficulty": "flat"
},
"flags": {
"has_toll": true,
"has_highway": true,
"has_ferry": true
},
"bounds": {
"min_lat": 123,
"min_lon": 123,
"max_lat": 123,
"max_lon": 123
}
}
],
"distance_meters": 123,
"duration_seconds": 123,
"flags": {
"has_toll": true,
"has_highway": true,
"has_ferry": true
},
"bounds": {
"min_lat": 123,
"min_lon": 123,
"max_lat": 123,
"max_lon": 123
},
"terrain": {
"total_ascent_meters": 123,
"total_descent_meters": 123,
"max_elevation_meters": 123,
"min_elevation_meters": 123,
"avg_grade_percent": 123,
"max_grade_percent": 123,
"elevation_profile": [
{
"distance_meters": 123,
"elevation_meters": 123
}
],
"difficulty": "flat"
},
"units": "<string>",
"narrative": "<string>"
},
"alternates": [
{
"waypoints": [
{
"lat": 123,
"lon": 123,
"original_index": 123
}
],
"legs": [
{
"distance_meters": 123,
"duration_seconds": 123,
"shape": "<string>",
"steps": [
{
"type": "none",
"instruction": "<string>",
"street_names": [
"<string>"
],
"distance_meters": 123,
"duration_seconds": 123,
"begin_shape_index": 123,
"end_shape_index": 123,
"travel_mode": "<string>",
"flags": {
"toll": true,
"ferry": true,
"rough": true,
"gate": true,
"highway": true
},
"verbal_alert": "<string>",
"verbal_instruction": "<string>",
"bearing_before": 123,
"bearing_after": 123,
"roundabout_exit_count": 123,
"exit_sign": {
"exit_number": "<string>",
"exit_branch": "<string>",
"exit_toward": "<string>",
"exit_name": "<string>"
},
"lanes": [
{
"indications": [
"<string>"
],
"valid": true,
"active": true
}
]
}
],
"terrain": {
"total_ascent_meters": 123,
"total_descent_meters": 123,
"max_elevation_meters": 123,
"min_elevation_meters": 123,
"avg_grade_percent": 123,
"max_grade_percent": 123,
"elevation_profile": [
{
"distance_meters": 123,
"elevation_meters": 123
}
],
"difficulty": "flat"
},
"flags": {
"has_toll": true,
"has_highway": true,
"has_ferry": true
},
"bounds": {
"min_lat": 123,
"min_lon": 123,
"max_lat": 123,
"max_lon": 123
}
}
],
"distance_meters": 123,
"duration_seconds": 123,
"flags": {
"has_toll": true,
"has_highway": true,
"has_ferry": true
},
"bounds": {
"min_lat": 123,
"min_lon": 123,
"max_lat": 123,
"max_lon": 123
},
"terrain": {
"total_ascent_meters": 123,
"total_descent_meters": 123,
"max_elevation_meters": 123,
"min_elevation_meters": 123,
"avg_grade_percent": 123,
"max_grade_percent": 123,
"elevation_profile": [
{
"distance_meters": 123,
"elevation_meters": 123
}
],
"difficulty": "flat"
},
"units": "<string>",
"narrative": "<string>"
}
],
"narrative": "<string>"
}{
"error": "<string>",
"message": "<string>"
}{
"error": "<string>",
"message": "<string>"
}Routing
Calculate Route
Calculate a route between two or more locations. Returns turn-by-turn directions with terrain analytics (ascent, descent, grade, difficulty) included by default. All distances are in meters, durations in seconds.
POST
/
v1
/
routing
/
route
curl --request POST \
--url https://api.footstep.ai/v1/routing/route \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"locations": [
{
"lat": 51.5322,
"lon": -0.124
},
{
"lat": 51.5055,
"lon": -0.0754
}
]
}
'{
"route": {
"waypoints": [
{
"lat": 123,
"lon": 123,
"original_index": 123
}
],
"legs": [
{
"distance_meters": 123,
"duration_seconds": 123,
"shape": "<string>",
"steps": [
{
"type": "none",
"instruction": "<string>",
"street_names": [
"<string>"
],
"distance_meters": 123,
"duration_seconds": 123,
"begin_shape_index": 123,
"end_shape_index": 123,
"travel_mode": "<string>",
"flags": {
"toll": true,
"ferry": true,
"rough": true,
"gate": true,
"highway": true
},
"verbal_alert": "<string>",
"verbal_instruction": "<string>",
"bearing_before": 123,
"bearing_after": 123,
"roundabout_exit_count": 123,
"exit_sign": {
"exit_number": "<string>",
"exit_branch": "<string>",
"exit_toward": "<string>",
"exit_name": "<string>"
},
"lanes": [
{
"indications": [
"<string>"
],
"valid": true,
"active": true
}
]
}
],
"terrain": {
"total_ascent_meters": 123,
"total_descent_meters": 123,
"max_elevation_meters": 123,
"min_elevation_meters": 123,
"avg_grade_percent": 123,
"max_grade_percent": 123,
"elevation_profile": [
{
"distance_meters": 123,
"elevation_meters": 123
}
],
"difficulty": "flat"
},
"flags": {
"has_toll": true,
"has_highway": true,
"has_ferry": true
},
"bounds": {
"min_lat": 123,
"min_lon": 123,
"max_lat": 123,
"max_lon": 123
}
}
],
"distance_meters": 123,
"duration_seconds": 123,
"flags": {
"has_toll": true,
"has_highway": true,
"has_ferry": true
},
"bounds": {
"min_lat": 123,
"min_lon": 123,
"max_lat": 123,
"max_lon": 123
},
"terrain": {
"total_ascent_meters": 123,
"total_descent_meters": 123,
"max_elevation_meters": 123,
"min_elevation_meters": 123,
"avg_grade_percent": 123,
"max_grade_percent": 123,
"elevation_profile": [
{
"distance_meters": 123,
"elevation_meters": 123
}
],
"difficulty": "flat"
},
"units": "<string>",
"narrative": "<string>"
},
"alternates": [
{
"waypoints": [
{
"lat": 123,
"lon": 123,
"original_index": 123
}
],
"legs": [
{
"distance_meters": 123,
"duration_seconds": 123,
"shape": "<string>",
"steps": [
{
"type": "none",
"instruction": "<string>",
"street_names": [
"<string>"
],
"distance_meters": 123,
"duration_seconds": 123,
"begin_shape_index": 123,
"end_shape_index": 123,
"travel_mode": "<string>",
"flags": {
"toll": true,
"ferry": true,
"rough": true,
"gate": true,
"highway": true
},
"verbal_alert": "<string>",
"verbal_instruction": "<string>",
"bearing_before": 123,
"bearing_after": 123,
"roundabout_exit_count": 123,
"exit_sign": {
"exit_number": "<string>",
"exit_branch": "<string>",
"exit_toward": "<string>",
"exit_name": "<string>"
},
"lanes": [
{
"indications": [
"<string>"
],
"valid": true,
"active": true
}
]
}
],
"terrain": {
"total_ascent_meters": 123,
"total_descent_meters": 123,
"max_elevation_meters": 123,
"min_elevation_meters": 123,
"avg_grade_percent": 123,
"max_grade_percent": 123,
"elevation_profile": [
{
"distance_meters": 123,
"elevation_meters": 123
}
],
"difficulty": "flat"
},
"flags": {
"has_toll": true,
"has_highway": true,
"has_ferry": true
},
"bounds": {
"min_lat": 123,
"min_lon": 123,
"max_lat": 123,
"max_lon": 123
}
}
],
"distance_meters": 123,
"duration_seconds": 123,
"flags": {
"has_toll": true,
"has_highway": true,
"has_ferry": true
},
"bounds": {
"min_lat": 123,
"min_lon": 123,
"max_lat": 123,
"max_lon": 123
},
"terrain": {
"total_ascent_meters": 123,
"total_descent_meters": 123,
"max_elevation_meters": 123,
"min_elevation_meters": 123,
"avg_grade_percent": 123,
"max_grade_percent": 123,
"elevation_profile": [
{
"distance_meters": 123,
"elevation_meters": 123
}
],
"difficulty": "flat"
},
"units": "<string>",
"narrative": "<string>"
}
],
"narrative": "<string>"
}{
"error": "<string>",
"message": "<string>"
}{
"error": "<string>",
"message": "<string>"
}Authorizations
Your Footstep API key
Body
application/json
Waypoints (min 2, max 20)
Required array length:
2 - 20 elementsShow child attributes
Show child attributes
How to travel: auto (car), pedestrian, bicycle, bus, or truck
Available options:
auto, bicycle, pedestrian, bus, truck Fine-tuning options. Include only the key matching your travel type.
Show child attributes
Show child attributes
Available options:
kilometers, miles Language for instructions
Elevation sampling interval in meters
Required range:
10 <= x <= 200Number of alternate routes
Required range:
0 <= x <= 3Include an AI-generated natural-language summary in the response (adds ~500ms via llm-service).
Response format. footstep = optimised for app developers (encoded polyline, flat structure). geojson = standard GeoJSON FeatureCollection (decoded coordinates, immediately usable in Leaflet/Mapbox GL/deck.gl).
Available options:
footstep, geojson Response
Route with terrain analytics
A complete route with terrain analytics
Show child attributes
Show child attributes
Alternate routes (same shape as primary route). Populated only when alternates >= 1 was requested AND viable alternate routings were found; absent otherwise.
Show child attributes
Show child attributes
AI-generated natural-language summary of the route. Present only when narrative: true was requested and llm-service is configured.
⌘I