Skip to main content
POST
/
v1
/
routing
/
snap
curl --request POST \
  --url https://api.footstep.ai/v1/routing/snap \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "shape": [
    {
      "lat": 51.5322,
      "lon": -0.124
    },
    {
      "lat": 51.5013,
      "lon": -0.1228
    },
    {
      "lat": 51.5019,
      "lon": -0.1209
    },
    {
      "lat": 51.5025,
      "lon": -0.119
    }
  ]
}
'
{
  "snapped_shape": "<string>",
  "confidence": 0.5,
  "route": {
    "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,
    "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"
    }
  },
  "edges": [
    {
      "names": [
        "<string>"
      ],
      "length_m": 123,
      "speed_kph": 123,
      "road_class": "<string>",
      "surface": "<string>",
      "grade_percent": 123
    }
  ],
  "matched_points": [
    {
      "lat": 123,
      "lon": 123,
      "type": "matched",
      "distance_from_trace_m": 123,
      "edge_index": 123
    }
  ]
}

Authorizations

​
x-api-key
string
header
required

Your Footstep API key

Body

application/json

Provide either shape or encoded_polyline

​
shape
object[]
Required array length: 2 - 20000 elements
​
encoded_polyline
string
​
costing
enum<string>
default:auto
Available options:
auto,
bicycle,
pedestrian,
bus,
truck
​
output
enum<string>
default:route

route = directions with terrain, attributes = road details, both = combined

Available options:
route,
attributes,
both
​
gps_accuracy
number
default:5

GPS accuracy in meters

Required range: 1 <= x <= 100
​
search_radius
number
default:25

Search radius in meters

Required range: 1 <= x <= 100
​
elevation_interval
number
default:30
Required range: 10 <= x <= 200
​
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

Snapped trace with optional route and attributes

​
snapped_shape
string
required

Encoded polyline of snapped trace

​
confidence
number
required

Match confidence score (0-1)

Required range: 0 <= x <= 1
​
route
object

Present when output includes 'route'. Includes terrain analytics.

​
edges
object[]

Present when output includes 'attributes'. Road segment details.

​
matched_points
object[]

Per-point match quality details