Location

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/valhalla/main/json-schema/location.json",
  "title": "Location",
  "description": "A geographic location used as an input to Valhalla routing requests. Specifies coordinates and optional snapping and routing behavior.",
  "type": "object",
  "required": ["lat", "lon"],
  "properties": {
    "lat": {
      "type": "number",
      "minimum": -90,
      "maximum": 90,
      "description": "Latitude in decimal degrees."
    },
    "lon": {
      "type": "number",
      "minimum": -180,
      "maximum": 180,
      "description": "Longitude in decimal degrees."
    },
    "type": {
      "type": "string",
      "enum": ["break", "through", "via", "break_through"],
      "default": "break",
      "description": "Location type controlling route leg splitting and U-turn behavior. First and last locations are always break."
    },
    "name": {
      "type": "string",
      "description": "Label echoed in the response."
    },
    "street": {
      "type": "string",
      "description": "Street address hint for improved snapping."
    },
    "date_time": {
      "type": "string",
      "description": "Per-location ISO 8601 datetime override (YYYY-MM-DDTHH:MM)."
    },
    "heading": {
      "type": "integer",
      "minimum": 0,
      "maximum": 360,
      "description": "Preferred approach heading in degrees."
    },
    "heading_tolerance": {
      "type": "integer",
      "description": "Tolerance in degrees for heading filter (default 60)."
    },
    "radius": {
      "type": "integer",
      "minimum": 0,
      "description": "Candidate search radius in meters."
    },
    "minimum_reachability": {
      "type": "integer",
      "minimum": 0,
      "default": 50,
      "description": "Minimum number of reachable edges for a snap candidate."
    },
    "rank_candidates": {
      "type": "boolean",
      "default": true,
      "description": "Rank snap candidates by distance to input."
    },
    "preferred_side": {
      "type": "string",
      "enum": ["same", "opposite", "either"],
      "default": "either",
      "description": "Preferred side of road to snap to."
    },
    "search_filter": {
      "type": "object",
      "description": "Optional filters to exclude candidate edges based on road attributes.",
      "properties": {
        "exclude_tunnel": { "type": "boolean", "default": false },
        "exclude_bridge": { "type": "boolean", "default": false },
        "exclude_toll": { "type": "boolean", "default": false },
        "exclude_ramp": { "type": "boolean", "default": false },
        "exclude_ferry": { "type": "boolean", "default": false },
        "exclude_closures": { "type": "boolean", "default": true }
      }
    }
  }
}