RouteMatrixRequest

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/geoapify/json-schema/geoapify-route-matrix-request-schema.json",
  "title": "RouteMatrixRequest",
  "x-generated": "2026-11-05",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/geoapify-route-matrix-api-openapi.yml#/components/schemas/RouteMatrixRequest",
  "type": "object",
  "required": [
    "mode",
    "sources",
    "targets"
  ],
  "properties": {
    "mode": {
      "type": "string",
      "enum": [
        "walk",
        "hike",
        "scooter",
        "motorcycle",
        "drive",
        "light_truck",
        "bicycle",
        "mountain_bike",
        "road_bike",
        "bus",
        "medium_truck",
        "truck",
        "truck_dangerous_goods",
        "heavy_truck",
        "long_truck"
      ],
      "description": "Travel profile used to calculate speeds, access rules, and road restrictions. `drive` represents a passenger car."
    },
    "sources": {
      "type": "array",
      "minItems": 1,
      "maxItems": 1000,
      "description": "Origin locations. Each source produces one row in `sources_to_targets`.",
      "items": {
        "$ref": "#/$defs/MatrixLocation"
      }
    },
    "targets": {
      "type": "array",
      "minItems": 1,
      "maxItems": 1000,
      "description": "Destination locations. Each target produces one column in every `sources_to_targets` row.",
      "items": {
        "$ref": "#/$defs/MatrixLocation"
      }
    },
    "avoid": {
      "type": "array",
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "type"
        ],
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "tolls",
              "ferries",
              "highways",
              "green_zones",
              "transfers",
              "locations",
              "polygons",
              "country_codes"
            ]
          },
          "importance": {
            "type": "number",
            "minimum": 0,
            "maximum": 1
          },
          "values": {
            "type": "array",
            "items": {}
          }
        }
      },
      "maxItems": 100,
      "description": "Road features, locations, polygons, or countries the router should avoid. Each rule requires a `type`; `importance` ranges from 0 to 1."
    },
    "traffic": {
      "type": "string",
      "enum": [
        "free_flow",
        "approximated"
      ],
      "default": "free_flow",
      "description": "Traffic model for motorized modes. `free_flow` assumes uncongested roads; `approximated` reduces speeds on roads likely to be congested."
    },
    "type": {
      "type": "string",
      "enum": [
        "balanced",
        "short",
        "less_maneuvers"
      ],
      "default": "balanced",
      "description": "Route preference. `balanced` balances time and distance; `short` prioritizes distance; `less_maneuvers` penalizes turns."
    },
    "max_speed": {
      "type": "number",
      "minimum": 6.5,
      "maximum": 252,
      "description": "Maximum speed for driving, truck, and bus modes. Use 10–252 km/h with `units=metric`, or 6.5–155 mph with `units=imperial`."
    },
    "units": {
      "type": "string",
      "enum": [
        "metric",
        "imperial"
      ],
      "default": "metric",
      "description": "Unit system for matrix distances. `metric` returns meters; `imperial` returns miles."
    }
  },
  "$defs": {
    "MatrixLocation": {
      "type": "object",
      "required": [
        "location"
      ],
      "properties": {
        "location": {
          "type": "array",
          "minItems": 2,
          "maxItems": 2,
          "prefixItems": [
            {
              "type": "number",
              "minimum": -180,
              "maximum": 180,
              "description": "Longitude."
            },
            {
              "type": "number",
              "minimum": -90,
              "maximum": 90,
              "description": "Latitude."
            }
          ],
          "items": false,
          "description": "Coordinate in GeoJSON order: `[longitude, latitude]`."
        }
      }
    }
  }
}