Geoapify · Schema
RoutePlannerRequest
GeocodingGeospatialLocationMapsRoutingPlacesTimezoneMCPGeoJSONOpenStreetMapStatic MapsIsolines
Properties
| Name | Type | Description |
|---|---|---|
| mode | string | Travel profile used for all agent routes. `drive` represents passenger cars. |
| agents | array | Resources—such as vehicles or workers—to which jobs and shipments can be assigned. |
| jobs | array | Independent service or delivery tasks. At least one job or shipment is required. |
| shipments | array | Paired pickup-delivery tasks. Pickup always precedes delivery and both are assigned to the same agent. |
| locations | array | Reusable coordinates referenced by zero-based `location_index` fields. Regular calls may contain at most 300 unique coordinates across the complete task. |
| avoid | array | Road features, locations, polygons, or countries the calculated agent routes should avoid. |
| traffic | string | Traffic model for motorized modes. `free_flow` assumes uncongested roads; `approximated` accounts for likely congestion. |
| type | string | Route preference used for agent travel. `balanced` balances time and distance; `short` prioritizes distance; `less_maneuvers` penalizes turns. |
| max_speed | number | 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 | string | Unit system for returned route distances. `metric` returns meters; `imperial` returns miles. |
JSON Schema
{
"$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
}
}
}
}
}
}Work with this as data
Every JSON Schema here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for schemas
4 MCP tools reach this
find_json_schemasBrowse and filter every JSON Schema in the catalog.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This JSON Schema
curl "https://apis.io/api/v1/json-schemas/geoapify-route-planner-request"
All schemas
curl "https://apis.io/api/v1/json-schemas?limit=25"Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.