{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/geoapify/json-schema/geoapify-route-planner-request-schema.json",
  "title": "RoutePlannerRequest",
  "x-generated": "2026-11-05",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/geoapify-route-planner-api-openapi.yml#/components/schemas/RoutePlannerRequest",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "mode",
    "agents"
  ],
  "anyOf": [
    {
      "required": [
        "jobs"
      ],
      "properties": {
        "jobs": {
          "minItems": 1
        }
      }
    },
    {
      "required": [
        "shipments"
      ],
      "properties": {
        "shipments": {
          "minItems": 1
        }
      }
    }
  ],
  "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 for all agent routes. `drive` represents passenger cars."
    },
    "agents": {
      "type": "array",
      "minItems": 1,
      "maxItems": 100,
      "description": "Resources—such as vehicles or workers—to which jobs and shipments can be assigned.",
      "items": {
        "$ref": "#/$defs/PlannerAgent"
      }
    },
    "jobs": {
      "type": "array",
      "maxItems": 1000,
      "description": "Independent service or delivery tasks. At least one job or shipment is required.",
      "items": {
        "$ref": "#/$defs/PlannerJob"
      }
    },
    "shipments": {
      "type": "array",
      "maxItems": 1000,
      "description": "Paired pickup-delivery tasks. Pickup always precedes delivery and both are assigned to the same agent.",
      "items": {
        "$ref": "#/$defs/PlannerShipment"
      }
    },
    "locations": {
      "type": "array",
      "maxItems": 1000,
      "description": "Reusable coordinates referenced by zero-based `location_index` fields. Regular calls may contain at most 300 unique coordinates across the complete task.",
      "items": {
        "$ref": "#/$defs/PlannerLocation"
      }
    },
    "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 calculated agent routes should avoid."
    },
    "traffic": {
      "type": "string",
      "enum": [
        "free_flow",
        "approximated"
      ],
      "default": "free_flow",
      "description": "Traffic model for motorized modes. `free_flow` assumes uncongested roads; `approximated` accounts for likely congestion."
    },
    "type": {
      "type": "string",
      "enum": [
        "balanced",
        "short",
        "less_maneuvers"
      ],
      "default": "balanced",
      "description": "Route preference used for agent travel. `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 returned route distances. `metric` returns meters; `imperial` returns miles."
    }
  },
  "$defs": {
    "PlannerAgent": {
      "type": "object",
      "additionalProperties": false,
      "anyOf": [
        {
          "required": [
            "start_location"
          ]
        },
        {
          "required": [
            "start_location_index"
          ]
        },
        {
          "required": [
            "end_location"
          ]
        },
        {
          "required": [
            "end_location_index"
          ]
        }
      ],
      "allOf": [
        {
          "not": {
            "required": [
              "start_location",
              "start_location_index"
            ]
          }
        },
        {
          "not": {
            "required": [
              "end_location",
              "end_location_index"
            ]
          }
        },
        {
          "not": {
            "required": [
              "pickup_capacity",
              "delivery_capacity"
            ]
          }
        }
      ],
      "properties": {
        "id": {
          "type": "string",
          "minLength": 1,
          "maxLength": 100,
          "description": "Optional unique agent identifier."
        },
        "start_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": "Agent start coordinate. Alternative to `start_location_index`."
        },
        "end_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": "Optional agent end coordinate. Alternative to `end_location_index`."
        },
        "start_location_index": {
          "type": "integer",
          "minimum": 0,
          "description": "Zero-based index in `locations` for the agent start."
        },
        "end_location_index": {
          "type": "integer",
          "minimum": 0,
          "description": "Zero-based index in `locations` for the agent end."
        },
        "pickup_capacity": {
          "type": "number",
          "minimum": 0,
          "description": "Maximum amount the agent can pick up."
        },
        "delivery_capacity": {
          "type": "number",
          "minimum": 0,
          "description": "Maximum amount initially loaded for delivery."
        },
        "capabilities": {
          "type": "array",
          "maxItems": 1000,
          "uniqueItems": true,
          "description": "Capabilities available to satisfy job or shipment `requirements`.",
          "items": {
            "type": "string",
            "pattern": "^[A-Za-z0-9_. -]{1,100}$"
          }
        },
        "time_windows": {
          "type": "array",
          "maxItems": 10,
          "description": "Agent availability windows in relative seconds.",
          "items": {
            "type": "array",
            "minItems": 2,
            "maxItems": 2,
            "prefixItems": [
              {
                "type": "number",
                "minimum": 0,
                "description": "Interval start in relative seconds."
              },
              {
                "type": "number",
                "minimum": 0,
                "description": "Interval end in relative seconds."
              }
            ],
            "items": false
          }
        },
        "breaks": {
          "type": "array",
          "maxItems": 10,
          "description": "Optional breaks scheduled within one of their allowed time windows.",
          "items": {
            "$ref": "#/$defs/PlannerBreak"
          }
        },
        "description": {
          "type": "string",
          "maxLength": 1000,
          "description": "Optional human-readable agent description."
        }
      }
    },
    "PlannerBreak": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "time_windows"
      ],
      "properties": {
        "duration": {
          "type": "number",
          "minimum": 0,
          "default": 0,
          "description": "Break duration in seconds."
        },
        "time_windows": {
          "type": "array",
          "maxItems": 10,
          "description": "Intervals in which the break may start.",
          "items": {
            "type": "array",
            "minItems": 2,
            "maxItems": 2,
            "prefixItems": [
              {
                "type": "number",
                "minimum": 0,
                "description": "Interval start in relative seconds."
              },
              {
                "type": "number",
                "minimum": 0,
                "description": "Interval end in relative seconds."
              }
            ],
            "items": false
          }
        }
      }
    },
    "PlannerJob": {
      "type": "object",
      "additionalProperties": false,
      "oneOf": [
        {
          "required": [
            "location"
          ]
        },
        {
          "required": [
            "location_index"
          ]
        }
      ],
      "allOf": [
        {
          "not": {
            "required": [
              "pickup_amount",
              "delivery_amount"
            ]
          }
        }
      ],
      "properties": {
        "id": {
          "type": "string",
          "minLength": 1,
          "maxLength": 100,
          "description": "Optional unique job identifier."
        },
        "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": "Job coordinate. Alternative to `location_index`."
        },
        "location_index": {
          "type": "integer",
          "minimum": 0,
          "description": "Zero-based index in `locations`. Alternative to `location`."
        },
        "priority": {
          "type": "integer",
          "minimum": 0,
          "maximum": 100,
          "default": 0,
          "description": "Assignment priority from 0 (lowest) to 100 (highest)."
        },
        "duration": {
          "type": "number",
          "minimum": 0,
          "default": 0,
          "description": "Service duration in seconds."
        },
        "pickup_amount": {
          "type": "number",
          "minimum": 0,
          "description": "Amount added to the agent pickup load."
        },
        "delivery_amount": {
          "type": "number",
          "minimum": 0,
          "description": "Amount removed from the agent delivery load."
        },
        "requirements": {
          "type": "array",
          "maxItems": 1000,
          "uniqueItems": true,
          "description": "Capabilities an agent must have to perform the job.",
          "items": {
            "type": "string",
            "pattern": "^[A-Za-z0-9_. -]{1,100}$"
          }
        },
        "time_windows": {
          "type": "array",
          "maxItems": 10,
          "description": "Intervals in which an agent must reach the job.",
          "items": {
            "type": "array",
            "minItems": 2,
            "maxItems": 2,
            "prefixItems": [
              {
                "type": "number",
                "minimum": 0,
                "description": "Interval start in relative seconds."
              },
              {
                "type": "number",
                "minimum": 0,
                "description": "Interval end in relative seconds."
              }
            ],
            "items": false
          }
        },
        "description": {
          "type": "string",
          "maxLength": 1000,
          "description": "Optional human-readable job description."
        }
      }
    },
    "PlannerLocation": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "location"
      ],
      "properties": {
        "id": {
          "type": "string",
          "minLength": 1,
          "maxLength": 100,
          "description": "Optional unique location identifier returned with related plan actions and waypoints."
        },
        "description": {
          "type": "string",
          "maxLength": 1000,
          "description": "Optional human-readable location label."
        },
        "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": "Reusable coordinate in GeoJSON order: `[longitude, latitude]`."
        }
      }
    },
    "PlannerShipment": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "pickup",
        "delivery"
      ],
      "properties": {
        "id": {
          "type": "string",
          "minLength": 1,
          "maxLength": 100,
          "description": "Optional unique shipment identifier."
        },
        "pickup": {
          "$ref": "#/$defs/PlannerShipmentStop"
        },
        "delivery": {
          "$ref": "#/$defs/PlannerShipmentStop"
        },
        "requirements": {
          "type": "array",
          "maxItems": 1000,
          "uniqueItems": true,
          "description": "Capabilities an agent must have to handle the shipment.",
          "items": {
            "type": "string",
            "pattern": "^[A-Za-z0-9_. -]{1,100}$"
          }
        },
        "priority": {
          "type": "integer",
          "minimum": 0,
          "maximum": 100,
          "default": 0,
          "description": "Assignment priority from 0 (lowest) to 100 (highest)."
        },
        "amount": {
          "type": "number",
          "minimum": 0,
          "description": "Shipment amount counted against agent capacity."
        },
        "description": {
          "type": "string",
          "maxLength": 1000,
          "description": "Optional human-readable shipment description."
        }
      }
    },
    "PlannerShipmentStop": {
      "type": "object",
      "additionalProperties": false,
      "oneOf": [
        {
          "required": [
            "location"
          ]
        },
        {
          "required": [
            "location_index"
          ]
        }
      ],
      "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": "Pickup or delivery coordinate. Alternative to `location_index`."
        },
        "location_index": {
          "type": "integer",
          "minimum": 0,
          "description": "Zero-based index in `locations`. Alternative to `location`."
        },
        "duration": {
          "type": "number",
          "minimum": 0,
          "default": 0,
          "description": "Pickup or delivery service duration in seconds."
        },
        "time_windows": {
          "type": "array",
          "maxItems": 10,
          "description": "Intervals in which an agent must reach this stop.",
          "items": {
            "type": "array",
            "minItems": 2,
            "maxItems": 2,
            "prefixItems": [
              {
                "type": "number",
                "minimum": 0,
                "description": "Interval start in relative seconds."
              },
              {
                "type": "number",
                "minimum": 0,
                "description": "Interval end in relative seconds."
              }
            ],
            "items": false
          }
        }
      }
    }
  }
}