Footstep Routing

Footstep Routing API

The Routing API provides terrain-intelligent routing, elevation queries, and spatial analysis. Every routing response includes terrain analytics by default: ascent, descent, grade profiles, and difficulty classification, without any extra configuration.

Design philosophy

Every endpoint works with just coordinates. Send locations, get a route with full terrain intelligence:

POST /v1/routing/route
{
  "locations": [
    { "lat": 51.5322, "lon": -0.1240 },
    { "lat": 51.5055, "lon": -0.0754 }
  ]
}

No transport mode, no options, no configuration required. The defaults give you a car route with terrain analytics, turn-by-turn directions, and an elevation profile. Power users can tune behaviour with optional parameters: travel to change how you travel, travel_options for fine-tuning preferences (hill avoidance, walking speed, vehicle dimensions), elevation_interval to control elevation sampling density, and language for localised navigation instructions.

Units

Numeric fields are always in SI base units regardless of the units request parameter — distances in meters, durations in seconds, elevations in meters, grades as a percentage, speeds in km/h. The units request parameter only affects the natural-language narrative summary; the response echoes that value back in narrative_units for reference.

Endpoints

All endpoints are POST requests under /v1/routing/:

Endpoint	Description
`POST /route`	Route between locations with terrain analytics and turn-by-turn directions
`POST /optimize`	Find the best order to visit multiple stops
`POST /snap`	Map-match GPS traces to the road network
`POST /elevation`	Elevation queries with computed summary statistics
`POST /isochrone`	Time or distance-based reachability polygons
`POST /matrix`	Time/distance matrices for logistics and dispatching
`POST /locate`	Snap coordinates to the nearest road with metadata

Authentication

All endpoints require an API key passed via the x-api-key header. See the authentication guide for details on key format, states, and security practices.

curl -X POST https://api.footstep.ai/v1/routing/route \
  -H "x-api-key: sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"locations": [{"lat": 51.5322, "lon": -0.1240}, {"lat": 51.5055, "lon": -0.0754}]}'

Travel types

All routing endpoints accept a travel parameter:

Travel	Description
`auto`	Car routing (default). Respects one-way streets, turn restrictions, and road hierarchy
`pedestrian`	Walking and hiking. Factors in terrain grade, avoids motorways, supports SAC hiking difficulty scale
`bicycle`	Cycling. Considers surface type, hill gradients. Supports road, hybrid, cross, and mountain bike types
`bus`	Bus routing. Similar to auto with bus-specific road access
`truck`	Truck routing. Respects vehicle height, width, weight, and axle load restrictions

Each travel type has its own travel_options for fine-tuning. For example, pedestrian supports use_hills (0 = avoid hills, 1 = prefer hills), walking_speed (0.5-25 km/h), and max_hiking_difficulty (0-6, SAC hiking scale). See the route endpoint for the full schema.

Multi-format support

Every endpoint accepts a format parameter:

Format	Content-Type	Best for
`footstep` (default)	`application/json`	App developers. Compact encoded polyline geometry, flat structure, optimised DX
`geojson`	`application/geo+json`	GIS tools. Standard GeoJSON FeatureCollection with decoded coordinates

GeoJSON responses work directly with Leaflet, Mapbox GL, deck.gl, and QGIS with no transformation needed.

{
  "locations": [...],
  "format": "geojson"
}

Terrain analytics

Routing responses include a terrain object at both the route and per-leg level:

{
  "terrain": {
    "total_ascent_meters": 12.4,
    "total_descent_meters": 8.1,
    "max_elevation_meters": 28,
    "min_elevation_meters": 5,
    "avg_grade_percent": 1.2,
    "max_grade_percent": 4.5,
    "elevation_profile": [
      { "distance_meters": 0, "elevation_meters": 22 },
      { "distance_meters": 30, "elevation_meters": 20 }
    ],
    "difficulty": "flat"
  }
}

The elevation_profile is an array of distance/elevation points sampled along the route. Control the sampling interval with the elevation_interval parameter (10-200 meters, default 30). The difficulty classification is based on average and maximum grade:

Difficulty	Average grade	Maximum grade
`flat`	< 2%	< 5%
`rolling`	< 4%	< 8%
`hilly`	< 6%	< 15%
`mountainous`	>= 6%	>= 15%

Route flags

Every route and leg includes a flags object indicating infrastructure used:

{
  "flags": {
    "has_toll": false,
    "has_highway": true,
    "has_ferry": false
  }
}

Use these to inform users about tolls, filter routes, or display warnings in your UI.

Route narratives

Pass narrative: true to get an AI-generated natural language summary of the route. Useful for accessibility descriptions, trip previews, and chatbot integrations.

{
  "locations": [
    { "lat": 51.5322, "lon": -0.1240 },
    { "lat": 51.5055, "lon": -0.0754 }
  ],
  "narrative": true
}

The response includes a narrative field on the route object:

{
  "route": {
    "narrative": "A 5.8km drive south through central London, about 14 minutes. Head south from King's Cross through Clerkenwell, then east along the river to Tower Bridge. Mostly flat with 12m total ascent. No tolls or motorways."
  }
}

This parameter is available on the route and optimise endpoints. Adds ~500ms latency due to AI generation.

Documentation Index