Skip to main content
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:
FieldWhat it tells you
distance_metersTotal route distance in meters
duration_secondsEstimated travel time in seconds
terrain.total_ascent_metersTotal climbing over the route in meters
terrain.total_descent_metersTotal descending over the route in meters
terrain.elevation_profileArray of distance/elevation points for charting
terrain.difficultyOverall 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"
}
TravelUse case
autoCar routing (default)
pedestrianWalking and hiking. Factors in terrain, avoids motorways
bicycleCycling. Considers surface type and hill gradients
busBus routing
truckTruck 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.