Skip to main content
POST
/
v1
/
routing
/
search-along-route
curl --request POST \
  --url https://api.footstep.ai/v1/routing/search-along-route \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "locations": [
    {
      "lat": 51.5322,
      "lon": -0.124
    },
    {
      "lat": 51.5055,
      "lon": -0.0754
    }
  ],
  "search": "coffee shop",
  "max_detour_seconds": 300
}
'
{
  "route": {
    "waypoints": [
      {
        "lat": 123,
        "lon": 123,
        "original_index": 123
      }
    ],
    "legs": [
      {
        "distance_meters": 123,
        "duration_seconds": 123,
        "shape": "<string>",
        "steps": [
          {
            "type": "none",
            "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
            }
          ],
          "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_meters": 123,
    "duration_seconds": 123,
    "flags": {
      "has_toll": true,
      "has_highway": true,
      "has_ferry": true
    },
    "bounds": {
      "min_lat": 123,
      "min_lon": 123,
      "max_lat": 123,
      "max_lon": 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
        }
      ],
      "difficulty": "flat"
    },
    "units": "<string>",
    "narrative": "<string>"
  },
  "places": [
    {
      "place": {
        "coordinates": {
          "lat": 0,
          "lng": 0
        },
        "label": "<string>",
        "name": "<string>",
        "distance_meters": 123,
        "confidence": 0.5,
        "layer": "<string>",
        "source": "<string>",
        "country": "<string>",
        "country_code": "<string>",
        "region": "<string>",
        "locality": "<string>"
      },
      "detour_seconds": 123,
      "detour_meters": 123,
      "position_along_route_percent": 50
    }
  ]
}

Authorizations

​
x-api-key
string
header
required

Your Footstep API key

Body

application/json
​
locations
object[]
required

Route waypoints (min 2, max 20)

Required array length: 2 - 20 elements
​
search
string
required

What to search for along the route (e.g. 'coffee shop', 'petrol station', 'supermarket')

​
travel
enum<string>
default:auto
Available options:
auto,
bicycle,
pedestrian,
bus,
truck
​
travel_options
object

Fine-tuning options. Include only the key matching your travel type.

​
max_detour_seconds
number
default:300

Maximum acceptable detour in seconds (1 min to 1 hour)

Required range: 60 <= x <= 3600
​
size
integer
default:5

Maximum number of places to return

Required range: 1 <= x <= 20
​
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

Route with places found along the corridor

​
route
object
required

The original route between the locations

​
places
object[]
required

Places found along the route, ranked by detour time