# Mapbox Directions (Turn-by-Turn Routing)

> Mapbox Directions (Turn-by-Turn Routing) is a paid API for AI agents from ZeroClick x402 Service Registry at directions.withzero.ai, paid per call via MPP, $0.01/call, status unknown (last checked 2026-10-10).

Returns turn-by-turn driving, walking, or cycling directions between two locations, including distance, duration, step instructions, and an encoded polyline route geometry.

## Facts

- Endpoint: POST https://directions.withzero.ai/run?utm_source=zero.xyz
- Price: $0.01/call
- Payment: MPP
- Status: unknown
- Last checked: 2026-10-10
- Activations on Zero: 0
- Provider: ZeroClick x402 Service Registry
- Website: https://withzero.ai
- Tags: location, directions, routing, navigation, driving, mapbox, maps
- Canonical page: https://www.zero.xyz/c/zeroclick-x402-service-registry-directions-79a67476
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_X964inuCNBTcaTei2XUBL

Status and success rate cover calls made through Zero and Zero's own probes. Third-party monitors may report differently.

## How to call it through Zero

Zero handles the 402 payment challenge and records the run. With the Zero CLI installed (`npm i -g @zeroxyz/cli`):

```sh
zero fetch --capability zeroclick-x402-service-registry-directions-79a67476 -d '<json body>'
```

Example prompt: Get me walking directions from the Empire State Building at 40.7484,-73.9857 to Grand Central Terminal at 40.7527,-73.9772 — I want step-by-step instructions and the total distance.

## When to prefer this

Choose this endpoint when you need structured, step-by-step navigation directions between two specific points and want distance/duration alongside the route geometry. It is ideal when either addresses or lat/lng coordinates are available as input, and when the agent needs to present human-readable turn instructions or render a route on a map. Prefer this over a generic maps search when the goal is routing rather than place discovery.

## Known failure modes

- Invalid or unresolvable address causes geocoding failure — returns error with no route
- Origin and destination are the same or too close — may return empty or trivial route
- Unsupported travel mode value — rejected by schema validation
- No route available between points (e.g. island with no road) — Mapbox returns no-route error
- Malformed coordinate string (wrong format) — schema or geocoder rejects input

## How this service works

Get turn-by-turn driving, walking, or cycling directions between two locations via Mapbox. Accepts addresses or "lat,lng" coordinates for origin and destination. Returns total distance, duration, step-by-step instructions, and an encoded polyline. If addresses are provided they are automatically geocoded first.

## Output

A JSON object containing total route distance in meters, total duration in seconds, a road-name summary string, an array of turn-by-turn step objects (each with instruction text, step distance, and step duration), and an encoded polyline string representing the full route geometry.

## Example request

```json
{
 "mode": "walking",
 "origin": "40.7484,-73.9857",
 "destination": "40.7527,-73.9772"
}
```

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "required": [
  "origin",
  "destination"
 ],
 "properties": {
  "mode": {
   "enum": [
    "driving",
    "walking",
    "cycling",
    "driving-traffic"
   ],
   "type": "string",
   "default": "driving",
   "description": "Travel mode: driving (default), walking, cycling, or driving-traffic"
  },
  "origin": {
   "type": "string",
   "minLength": 1,
   "description": "Starting point — \"lat,lng\" coordinates or an address string"
  },
  "destination": {
   "type": "string",
   "minLength": 1,
   "description": "Ending point — \"lat,lng\" coordinates or an address string"
  }
 },
 "additionalProperties": false
}
```

## Response schema (JSON Schema)

```json
{
 "type": "object",
 "required": [
  "distance",
  "duration",
  "summary",
  "steps",
  "geometry"
 ],
 "properties": {
  "steps": {
   "type": "array",
   "items": {
    "type": "object",
    "required": [
     "instruction",
     "distance",
     "duration"
    ],
    "properties": {
     "distance": {
      "type": "number",
      "description": "Distance for this step in meters"
     },
     "duration": {
      "type": "number",
      "description": "Duration for this step in seconds"
     },
     "instruction": {
      "type": "string",
      "description": "Turn-by-turn instruction text"
     }
    },
    "additionalProperties": false
   },
   "description": "Turn-by-turn navigation steps"
  },
  "summary": {
   "type": "string",
   "description": "Route summary (road names)"
  },
  "distance": {
   "type": "number",
   "description": "Total distance in meters"
  },
  "duration": {
   "type": "number",
   "description": "Total duration in seconds"
  },
  "geometry": {
   "type": "string",
   "description": "Encoded polyline geometry of the route"
  }
 },
 "additionalProperties": false
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/zeroclick-x402-service-registry-directions-79a67476/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from directions.withzero.ai](https://www.zero.xyz/host/directions.withzero.ai/llms.txt)