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,
  "match_quality_reason": "<string>",
  "route": {
    "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,
    "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
        }
      ]
    }
  },
  "edges": [
    {
      "names": [
        "<string>"
      ],
      "length_meters": 123,
      "speed_kph": 123,
      "grade_percent": 123
    }
  ],
  "matched_points": [
    {
      "lat": 123,
      "lon": 123,
      "distance_from_trace_meters": 123,
      "edge_index": 123
    }
  ]
}

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

Provide either shape or encoded_polyline

​
shape
object[]
Required array length: 2 - 20000 elements
​
encoded_polyline
string
​
travel
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:10

Expected GPS accuracy in meters. Default 10 reflects typical urban phone GPS; bump higher for noisy traces, lower for high-quality recordings.

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
​
shape_match
enum<string>
default:walk_or_snap

Matching strategy. edge_walk requires the trace to follow exact road edges (high-quality data only). map_snap is strict per-point snapping. walk_or_snap (default) is forgiving — falls back to walking the closest edges when an exact snap fails, which matches typical phone-GPS behaviour.

Available options:
edge_walk,
map_snap,
walk_or_snap
​
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
​
match_quality
enum<string>

Present when the match is unreliable. Currently the only value is low (confidence below 0.5). Distance, duration, edges, and terrain are still populated but should be treated as approximate.

Available options:
low
​
match_quality_reason
string

Human-readable explanation of why match_quality is set. Present whenever match_quality is set.

​
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