Quickstart - Footstep

This guide covers routing between two coordinates and geocoding an address. You’ll need an API key from console.footstep.ai.

Get an API key

Sign up at console.footstep.ai and create an API key. Your key will look like sk_live_abc123.... Keep it safe, as it’s used to authenticate every request.

API keys are for server-side use only. Never expose them in frontend code, mobile apps, or anywhere a user could inspect network traffic.

Your first request

Every routing request needs at least two locations: a start and an end. Each location is a lat/lon pair. Here’s a route from King’s Cross to Tower Bridge in London:

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 }
    ]
  }'

const response = await fetch("https://api.footstep.ai/v1/routing/route", {
  method: "POST",
  headers: {
    "x-api-key": "sk_live_your_key_here",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    locations: [
      { lat: 51.5322, lon: -0.1240 },
      { lat: 51.5055, lon: -0.0754 },
    ],
  }),
});

const data = await response.json();

import requests

response = requests.post(
    "https://api.footstep.ai/v1/routing/route",
    headers={"x-api-key": "sk_live_your_key_here"},
    json={
        "locations": [
            {"lat": 51.5322, "lon": -0.1240},
            {"lat": 51.5055, "lon": -0.0754},
        ]
    },
)

data = response.json()

The defaults return a car route with terrain analytics. You can change this with the travel parameter.

Understand the response

The response contains a route object with everything you need:

{
  "route": {
    "distance_meters": 5765,
    "duration_seconds": 812,
    "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": 500, "elevation_meters": 18 },
        { "distance_meters": 1000, "elevation_meters": 15 }
      ],
      "difficulty": "flat"
    },
    "legs": [
      {
        "distance_meters": 5765,
        "duration_seconds": 812,
        "steps": [
          {
            "instruction": "Drive north on Midland Road.",
            "distance_meters": 120,
            "duration_seconds": 15
          }
        ]
      }
    ]
  }
}

Here’s what the key fields mean:

Field	What it tells you
`distance_meters`	Total route distance in meters
`duration_seconds`	Estimated travel time in seconds
`terrain.total_ascent_meters`	Total climbing over the route in meters
`terrain.total_descent_meters`	Total descending over the route in meters
`terrain.elevation_profile`	Array of distance/elevation points for charting
`terrain.difficulty`	Overall classification: `flat`, `rolling`, `hilly`, or `mountainous`
`legs[].steps[]`	Turn-by-turn directions with distance and time per manoeuvre

All field names include their unit. distance_meters is always meters, duration_seconds is always seconds, grade_percent is always a percentage. This is true regardless of the units parameter you send in the request.

Change how you travel

The default is auto (car). You can switch to walking, cycling, or other travel types using the travel parameter:

{
  "locations": [
    { "lat": 51.5322, "lon": -0.1240 },
    { "lat": 51.5055, "lon": -0.0754 }
  ],
  "travel": "pedestrian"
}

Travel	Use case
`auto`	Car routing (default)
`pedestrian`	Walking and hiking. Factors in terrain, avoids motorways
`bicycle`	Cycling. Considers surface type and hill gradients
`bus`	Bus routing
`truck`	Truck routing. Respects vehicle dimensions and weight limits

Each travel type produces different routes and terrain analytics. A pedestrian route through hilly terrain will show significantly different difficulty and grade profiles compared to the same coordinates with auto.

Try GeoJSON format

By default, responses use the footstep format, which is compact JSON with encoded polyline geometry. If you’re working with mapping libraries or GIS tools, you can request GeoJSON instead:

{
  "locations": [
    { "lat": 51.5322, "lon": -0.1240 },
    { "lat": 51.5055, "lon": -0.0754 }
  ],
  "format": "geojson"
}

This returns a standard GeoJSON FeatureCollection with decoded coordinate arrays. You can paste the response directly into geojson.io to visualise it, or load it into Leaflet, Mapbox GL, deck.gl, or QGIS without any transformation.

Try geocoding

Geocoding converts text into coordinates. Search for any address, place, or landmark:

curl "https://api.footstep.ai/v1/geocoding/search?text=Buckingham+Palace" \
  -H "x-api-key: sk_live_your_key_here"

const response = await fetch(
  "https://api.footstep.ai/v1/geocoding/search?text=Buckingham+Palace",
  { headers: { "x-api-key": "sk_live_your_key_here" } }
);

const data = await response.json();

import requests

response = requests.get(
    "https://api.footstep.ai/v1/geocoding/search",
    headers={"x-api-key": "sk_live_your_key_here"},
    params={"text": "Buckingham Palace"},
)

data = response.json()

Every result includes a confidence score and place type:

{
  "results": [
    {
      "coordinates": { "lat": 51.5014, "lng": -0.1419 },
      "label": "Buckingham Palace, London, England, United Kingdom",
      "name": "Buckingham Palace",
      "confidence": 0.95,
      "place_type": "venue"
    }
  ]
}

Use focus.point to bias results towards a location (e.g. the user’s city) and boundary.country to restrict to specific countries. See the geocoding guide for the full set of parameters and endpoints.

Next steps

Routing API

Terrain-intelligent routing, elevation, and spatial analysis.

Geocoding API

Search, reverse geocode, autocomplete, and batch processing.

Authentication

How API keys work, key states, and security practices.

Errors

Error codes, what triggers them, and how to handle retries.

​Get an API key

​Your first request

​Understand the response

​Change how you travel

​Try GeoJSON format

​Try geocoding

​Next steps

Routing API

Geocoding API

Authentication

Errors

Get an API key

Your first request

Understand the response

Change how you travel

Try GeoJSON format

Try geocoding

Next steps