Skip to main content
POST
/
v1
/
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": [
          {
            "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
            }
          ]
        },
        "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
        }
      ]
    },
    "units": "<string>",
    "narrative": "<string>"
  },
  "origin": {
    "coordinates": {
      "lat": 123,
      "lng": 123
    },
    "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>"
}

Documentation Index

Fetch the complete documentation index at: https://docs.footstep.ai/llms.txt

Use this file to discover all available pages before exploring further.

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).

​
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.

​
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

​
route
object
required

Route from origin to the geocoded destination

​
origin
object
required

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

​
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.

​
narrative
string

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