> ## 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.

# get_directions

> Get driving, walking, or cycling directions between locations

Get turn-by-turn directions between two or more locations. Supports car, pedestrian, bicycle, bus, and truck routing. Every response includes terrain analytics (elevation gain, difficulty, grade profiles) by default.

Your agent can also fine-tune the route: avoid hills, prefer lit streets, set vehicle dimensions for truck routing, or request alternate routes.

## Example prompts

* "Get me walking directions from Kings Cross to Tower Bridge"
* "How do I drive from Heathrow to Cambridge avoiding tolls?"
* "Plan a cycling route from Greenwich to Richmond Park that avoids hills"
* "What's the flattest walking route between these two coordinates?"

## What you get back

A full route with distance, duration, and turn-by-turn steps. Terrain analytics include total ascent/descent, elevation profile, grade percentages, and a difficulty classification (flat, rolling, hilly, or mountainous). Route flags (`has_toll`, `has_highway`, `has_ferry`) tell you if the route uses any of those — and are omitted entirely when none apply (the common case in urban routing). Only the truthy entries are emitted, so absence of a flag means it doesn't apply.

Each step carries `instruction`, `distance_meters`, `duration_seconds`, `travel_mode`, `type`, and `streets`. The `streets` array lists the named roads the step traverses; it's omitted on unnamed manoeuvres (forks, "destination on the left", some roundabout exits) so absence means "no street name to attach", not an empty list. Step-level `ferry`/`toll`/`highway` flags are emitted only when true.

### Step type values

`type` is one of a fixed set of manoeuvre kinds. Grouped by category:

| Category         | Values                                                                                                      |
| ---------------- | ----------------------------------------------------------------------------------------------------------- |
| **Start / end**  | `start`, `start_left`, `start_right`, `destination`, `destination_left`, `destination_right`                |
| **Direction**    | `left`, `right`, `slight_left`, `slight_right`, `sharp_left`, `sharp_right`, `u_turn_left`, `u_turn_right`  |
| **Continuation** | `continue`, `becomes`, `stay_straight`, `stay_left`, `stay_right`                                           |
| **Highway**      | `merge`, `merge_left`, `merge_right`, `ramp_straight`, `ramp_left`, `ramp_right`, `exit_left`, `exit_right` |
| **Roundabout**   | `roundabout_enter`, `roundabout_exit`                                                                       |
| **Ferry**        | `ferry_enter`, `ferry_exit`                                                                                 |
| **Fallback**     | `none`, `unknown`                                                                                           |

Treat the enum as a closed set — these are the only values an `auto`, `pedestrian`, `bicycle`, `bus`, or `truck` route will produce. The `none` and `unknown` values are present for completeness and shouldn't appear in normal output.

All numeric distance / duration fields are always in meters / seconds regardless of the request `units` (which only affects the natural-language `narrative` summary). Pass `narrative: true` for an AI-generated plain-English summary of the route — the response then also includes a `narrative_units` field telling you which units the summary was rendered in (`kilometers` or `miles`).

For 2-waypoint routes, the route's totals/terrain/flags are reported once at the top level — the single leg only carries `steps`. Multi-waypoint routes (3+ waypoints) keep the per-leg breakdown so you can see distance/terrain per segment. Geometry for the route lives in the `render` envelope as a GeoJSON `linestring` layer.

## Alternate routes: `alternates`

Set `alternates: 1-3` to request alternative routings. When found, the response carries an `alternates` array of full route objects (same shape as `route`), each with their own distance, duration, terrain analytics, and turn-by-turn steps. The LLM can reason about "which is flatter?" or "which avoids the highway?" by comparing them.

Alternates aren't always available — for short urban routes there often isn't a meaningfully different option. The `alternates` field is omitted when none are available.

## Map rendering

Responses include a `render` envelope with a `linestring` layer for the route. Pass `compact: true` for summary-only responses. See [response defaults & controls](/mcp/defaults) and [render envelopes](/mcp/render-envelopes).

## Example response

```json theme={null}
{
  "structuredContent": {
    "route": {
      "distance_meters": 5765,
      "duration_seconds": 812,
      "terrain": {
        "difficulty": "flat",
        "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
      },
      "legs": [{ "steps": [/* turn-by-turn directions */] }]
    },
    "render": [
      {
        "kind": "linestring",
        "label": "Route",
        "data": {
          "type": "Feature",
          "geometry": { "type": "LineString", "coordinates": [/* [lng, lat] pairs */] },
          "properties": {}
        },
        "bbox": [-0.13, 51.49, -0.06, 51.54]
      }
    ]
  }
}
```