curl --request POST \
--url https://api.footstep.ai/v1/routing/find-and-route \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"origin": {
"lat": 51.5322,
"lon": -0.124
},
"destination": "Tower Bridge, London",
"travel": "pedestrian"
}
'{
"destination": {
"coordinates": {
"lat": 0,
"lng": 0
},
"label": "<string>",
"name": "<string>",
"confidence": 0.5,
"place_type": "<string>",
"country": "<string>",
"country_code": "<string>",
"region": "<string>",
"county": "<string>",
"locality": "<string>",
"neighbourhood": "<string>"
},
"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>"
},
"origin": {
"coordinates": {
"lat": 123,
"lng": 123
},
"resolved_from": "string",
"name": "<string>",
"label": "<string>",
"place_type": "<string>",
"country": "<string>",
"country_code": "<string>"
},
"alternatives": [
{
"coordinates": {
"lat": 0,
"lng": 0
},
"label": "<string>",
"name": "<string>",
"confidence": 0.5,
"place_type": "<string>",
"country": "<string>",
"country_code": "<string>",
"region": "<string>",
"county": "<string>",
"locality": "<string>",
"neighbourhood": "<string>"
}
],
"narrative": "<string>"
}{
"error": "<string>",
"message": "<string>"
}{
"error": "<string>",
"message": "<string>"
}Find and Route
Find a place by name or address, then calculate a route to it from your origin. Combines geocoding and routing in a single call. Returns the matched destination, the full route with terrain analytics, and alternative geocoding matches.
curl --request POST \
--url https://api.footstep.ai/v1/routing/find-and-route \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"origin": {
"lat": 51.5322,
"lon": -0.124
},
"destination": "Tower Bridge, London",
"travel": "pedestrian"
}
'{
"destination": {
"coordinates": {
"lat": 0,
"lng": 0
},
"label": "<string>",
"name": "<string>",
"confidence": 0.5,
"place_type": "<string>",
"country": "<string>",
"country_code": "<string>",
"region": "<string>",
"county": "<string>",
"locality": "<string>",
"neighbourhood": "<string>"
},
"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>"
},
"origin": {
"coordinates": {
"lat": 123,
"lng": 123
},
"resolved_from": "string",
"name": "<string>",
"label": "<string>",
"place_type": "<string>",
"country": "<string>",
"country_code": "<string>"
},
"alternatives": [
{
"coordinates": {
"lat": 0,
"lng": 0
},
"label": "<string>",
"name": "<string>",
"confidence": 0.5,
"place_type": "<string>",
"country": "<string>",
"country_code": "<string>",
"region": "<string>",
"county": "<string>",
"locality": "<string>",
"neighbourhood": "<string>"
}
],
"narrative": "<string>"
}{
"error": "<string>",
"message": "<string>"
}{
"error": "<string>",
"message": "<string>"
}Authorizations
Your Footstep API key
Body
Starting location. Either lat/lon coordinates, or a place name / postcode / address (geocoded internally).
Show child attributes
Show child attributes
Place name, address, or landmark to find and route to
ISO 3166-1 alpha-3 country code hint for geocoding (e.g. GBR, USA)
auto, bicycle, pedestrian, bus, truck Fine-tuning options. Include only the key matching your travel type.
Show child attributes
Show child attributes
10 <= x <= 200Include a natural language route summary. Adds ~500ms.
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).
footstep, geojson ISO 3166-1 alpha-3 country hint applied when origin is a string.
Response
Geocoded destination with route
The geocoded destination that was routed to
Show child attributes
Show child attributes
Route from origin to the geocoded destination
Show child attributes
Show child attributes
Echoed origin — coordinates always present; geocoded label/name fields present only when the caller passed a string.
Show child attributes
Show child attributes
Other geocoding matches (up to 3) in case the primary result wasn't what you meant. Filtered to the same country as the primary match with a minimum confidence threshold; absent when nothing useful survives the filter.
Show child attributes
Show child attributes
AI-generated 1-3 sentence summary of the route. Present only when narrative: true was requested and the LLM service was available.