Valhalla · Schema

RouteRequest

Request body for the Valhalla /route endpoint. Computes a turn-by-turn route between two or more locations.

RoutingNavigationOpenStreetMapMappingGeospatialDirectionsIsochronesTravelTransportationOpen Source

Properties

Name Type Description
locations array Ordered list of route waypoints. First and last are always break-type stops.
costing string Travel mode costing model.
costing_options object Per-costing-model fine-tuning options.
id string Arbitrary request identifier echoed in the response.
units string
language string BCP47 locale for narrative instructions.
directions_type string
alternates integer Number of alternative routes to return (max 3, forced to 0 for more than 2 waypoints).
shape_format string
date_time object
exclude_locations array Locations to avoid during routing.
exclude_polygons object Polygons defining areas to avoid.
elevation_interval number Elevation sample interval in meters. 0 disables elevation data.
turn_lanes boolean Include lane-level guidance per maneuver.
roundabout_exits boolean Include exit instructions at roundabouts.
View JSON Schema on GitHub

JSON Schema

route-request.json Raw ↑ 
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/valhalla/main/json-schema/route-request.json",
  "title": "RouteRequest",
  "description": "Request body for the Valhalla /route endpoint. Computes a turn-by-turn route between two or more locations.",
  "type": "object",
  "required": ["locations", "costing"],
  "properties": {
    "locations": {
      "type": "array",
      "minItems": 2,
      "description": "Ordered list of route waypoints. First and last are always break-type stops.",
      "items": { "$ref": "location.json" }
    },
    "costing": {
      "type": "string",
      "enum": ["auto", "bicycle", "pedestrian", "truck", "bus", "taxi", "motor_scooter", "motorcycle", "multimodal", "bikeshare", "auto_pedestrian"],
      "description": "Travel mode costing model."
    },
    "costing_options": {
      "type": "object",
      "description": "Per-costing-model fine-tuning options.",
      "properties": {
        "auto": { "type": "object" },
        "bicycle": { "type": "object" },
        "pedestrian": { "type": "object" },
        "truck": { "type": "object" },
        "motorcycle": { "type": "object" },
        "motor_scooter": { "type": "object" },
        "multimodal": { "type": "object" }
      }
    },
    "id": {
      "type": "string",
      "description": "Arbitrary request identifier echoed in the response."
    },
    "units": {
      "type": "string",
      "enum": ["km", "miles", "mi"],
      "default": "km"
    },
    "language": {
      "type": "string",
      "default": "en-US",
      "description": "BCP47 locale for narrative instructions."
    },
    "directions_type": {
      "type": "string",
      "enum": ["none", "maneuvers", "instructions"],
      "default": "instructions"
    },
    "alternates": {
      "type": "integer",
      "minimum": 0,
      "default": 0,
      "description": "Number of alternative routes to return (max 3, forced to 0 for more than 2 waypoints)."
    },
    "shape_format": {
      "type": "string",
      "enum": ["polyline6", "polyline5", "geojson", "no_shape"],
      "default": "polyline6"
    },
    "date_time": {
      "type": "object",
      "properties": {
        "type": {
          "type": "integer",
          "enum": [0, 1, 2, 3],
          "description": "0=current, 1=depart_at, 2=arrive_by, 3=invariant"
        },
        "value": {
          "type": "string",
          "description": "ISO 8601 datetime string (YYYY-MM-DDTHH:MM). Required for types 1-3."
        }
      }
    },
    "exclude_locations": {
      "type": "array",
      "items": { "$ref": "location.json" },
      "description": "Locations to avoid during routing."
    },
    "exclude_polygons": {
      "description": "Polygons defining areas to avoid.",
      "oneOf": [
        {
          "type": "array",
          "items": {
            "type": "array",
            "items": {
              "type": "array",
              "items": { "type": "number" },
              "minItems": 2,
              "maxItems": 2
            }
          }
        },
        {
          "type": "object",
          "properties": {
            "type": { "type": "string", "enum": ["FeatureCollection"] },
            "features": { "type": "array" }
          }
        }
      ]
    },
    "elevation_interval": {
      "type": "number",
      "minimum": 0,
      "default": 0,
      "description": "Elevation sample interval in meters. 0 disables elevation data."
    },
    "turn_lanes": {
      "type": "boolean",
      "default": false,
      "description": "Include lane-level guidance per maneuver."
    },
    "roundabout_exits": {
      "type": "boolean",
      "default": true,
      "description": "Include exit instructions at roundabouts."
    }
  }
}