Find and Route

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>"
}

POST

routing

find-and-route

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

x-api-key

string

header

required

Your Footstep API key

Body

application/json

origin

required

Starting location. Either lat/lon coordinates, or a place name / postcode / address (geocoded internally).

Show child attributes

destination

string

required

Place name, address, or landmark to find and route to

destination_country

string

ISO 3166-1 alpha-3 country code hint for geocoding (e.g. GBR, USA)

travel

enum<string>

default:auto

Available options:

auto,

bicycle,

pedestrian,

bus,

truck

travel_options

object

Fine-tuning options. Include only the key matching your travel type.

Show child attributes

elevation_interval

number

default:30

Required range: 10 <= x <= 200

narrative

boolean

default:false

Include a natural language route summary. Adds ~500ms.

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

origin_country

string

ISO 3166-1 alpha-3 country hint applied when origin is a string.

Response

Geocoded destination with route

destination

object

required

The geocoded destination that was routed to

Show child attributes

route

object

required

Route from origin to the geocoded destination

Show child attributes

origin

object

required

Echoed origin — coordinates always present; geocoded label/name fields present only when the caller passed a string.

Show child attributes

alternatives

object[]

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

narrative

string

AI-generated 1-3 sentence summary of the route. Present only when narrative: true was requested and the LLM service was available.

Routing

Geocoding

Natural Language

Predict

Authorizations

Body

Response