Skip to main content
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_m": 123,
        "duration_s": 123,
        "shape": "<string>",
        "steps": [
          {
            "type": "none",
            "instruction": "<string>",
            "street_names": [
              "<string>"
            ],
            "distance_m": 123,
            "duration_s": 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_m": 123,
          "total_descent_m": 123,
          "max_elevation_m": 123,
          "min_elevation_m": 123,
          "avg_grade_percent": 123,
          "max_grade_percent": 123,
          "elevation_profile": [
            {
              "distance_m": 123,
              "elevation_m": 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_m": 123,
    "duration_s": 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_m": 123,
      "total_descent_m": 123,
      "max_elevation_m": 123,
      "min_elevation_m": 123,
      "avg_grade_percent": 123,
      "max_grade_percent": 123,
      "elevation_profile": [
        {
          "distance_m": 123,
          "elevation_m": 123
        }
      ],
      "difficulty": "flat"
    },
    "units": "<string>"
  },
  "alternates": [
    {
      "waypoints": [
        {
          "lat": 123,
          "lon": 123,
          "original_index": 123
        }
      ],
      "legs": [
        {
          "distance_m": 123,
          "duration_s": 123,
          "shape": "<string>",
          "steps": [
            {
              "type": "none",
              "instruction": "<string>",
              "street_names": [
                "<string>"
              ],
              "distance_m": 123,
              "duration_s": 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_m": 123,
            "total_descent_m": 123,
            "max_elevation_m": 123,
            "min_elevation_m": 123,
            "avg_grade_percent": 123,
            "max_grade_percent": 123,
            "elevation_profile": [
              {
                "distance_m": 123,
                "elevation_m": 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_m": 123,
      "duration_s": 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_m": 123,
        "total_descent_m": 123,
        "max_elevation_m": 123,
        "min_elevation_m": 123,
        "avg_grade_percent": 123,
        "max_grade_percent": 123,
        "elevation_profile": [
          {
            "distance_m": 123,
            "elevation_m": 123
          }
        ],
        "difficulty": "flat"
      },
      "units": "<string>"
    }
  ]
}

Authorizations

​
x-api-key
string
header
required

Your Footstep API key

Body

application/json
​
locations
object[]
required

Waypoints (min 2, max 20)

Required array length: 2 - 20 elements
​
costing
enum<string>
default:auto

Transport mode

Available options:
auto,
bicycle,
pedestrian,
bus,
truck
​
costing_options
object

Mode-specific tuning. Include only the key matching your costing mode.

​
units
enum<string>
default:kilometers
Available options:
kilometers,
miles
​
language
string
default:en-GB

Language for instructions

​
elevation_interval
number
default:30

Elevation sampling interval in meters

Required range: 10 <= x <= 200
​
alternates
number
default:0

Number of alternate routes

Required range: 0 <= x <= 3
​
format
enum<string>
default:footstep

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

​
route
object
required

A complete route with terrain analytics

​
alternates
object[]

Alternate routes (same shape as primary route)