swagger.json

{
    "swagger": "2.0",
    "info": {
        "title": "Tour Optimization API",
        "description": "Our Tour Optimization API solves the so called vehicle routing problem fast. It calculates an optimal tour for a set of vehicles, services and constraints",
        "version": "1.0"
    },
    "host": "graphhopper.com",
    "basePath": "/api/1/vrp",
    "schemes": [
        "https"
    ],
    "produces": [
        "application/json"
    ],
    "security": [{
            "api_key": []
        }],
    "securityDefinitions": {
        "api_key": {
            "type": "apiKey",
            "name": "key",
            "in": "query"
        }
    },
    "paths": {
        "/optimize": {
            "post": {
                "summary": "Solves large routing problems",
                "description": "This endpoint solves large problems, i.e. traveling salesman or vehicle routing problems, and returns the solution.\n",
                "operationId": "postVrp",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "parameters": [{
                        "in": "query",
                        "name": "key",
                        "description": "your API key",
                        "required": true,
                        "type": "string"
                    }, {
                        "in": "body",
                        "name": "body",
                        "description": "Request object that contains the problem to be solved",
                        "required": true,
                        "schema": {
                            "$ref": "#/definitions/Request"
                        }
                    }
                ],
                "tags": [
                    "vrp"
                ],
                "responses": {
                    "200": {
                        "description": "A jobId you can use to retrieve your solution from server - see solution endpoint.",
                        "schema": {
                            "$ref": "#/definitions/JobId"
                        }
                    },
                    "400": {
                        "description": "Error occurred when reading client request. Request is invalid."
                    },
                    "500": {
                        "description": "Error occurred on server side."
                    }
                }
            }
        },
        "/solution/{jobId}": {
            "get": {
                "summary": "Return the solution associated to the jobId",
                "description": "This endpoint returns the solution of a large problems. You can fetch it with the job_id, you have been sent.\n",
                "operationId": "getSolution",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "parameters": [{
                        "in": "query",
                        "name": "key",
                        "description": "your API key",
                        "required": true,
                        "type": "string"
                    }, {
                        "in": "path",
                        "name": "jobId",
                        "description": "Request solution with jobId",
                        "required": true,
                        "type": "string"
                    }
                ],
                "tags": [
                    "solution"
                ],
                "responses": {
                    "200": {
                        "description": "A response containing the solution",
                        "schema": {
                            "$ref": "#/definitions/LargeResponse"
                        }
                    },
                    "400": {
                        "description": "Error occurred on client side such as invalid input."
                    },
                    "500": {
                        "description": "Error occurred on server side."
                    }
                }
            }
        }
    },
    "definitions": {
        "JobId": {
            "properties": {
                "job_id": {
                    "type": "string",
                    "description": "unique id for your job/request with which you can fetch your solution"
                }
            }
        },
        "Request": {
            "properties": {
                "vehicles": {
                    "type": "array",
                    "description": "An array of vehicles that can be employed",
                    "items": {
                        "$ref": "#/definitions/Vehicle"
                    }
                },
                "vehicle_types": {
                    "type": "array",
                    "description": "An array of vehicle types",
                    "items": {
                        "$ref": "#/definitions/VehicleType"
                    }
                },
                "services": {
                    "type": "array",
                    "description": "An array of services",
                    "items": {
                        "$ref": "#/definitions/Service"
                    }
                },
                "shipments": {
                    "type": "array",
                    "description": "An array of shipments",
                    "items": {
                        "$ref": "#/definitions/Shipment"
                    }
                }
            }
        },
        "Vehicle": {
            "properties": {
                "vehicle_id": {
                    "type": "string",
                    "description": "Unique identifier of vehicle"
                },
                "type_id": {
                    "type": "string",
                    "description": "Unique identifier referring to the available vehicle types"
                },
                "start_address": {
                    "$ref": "#/definitions/Address"
                },
                "end_address": {
                    "$ref": "#/definitions/Address"
                },
                "return_to_depot": {
                    "type": "boolean",
                    "description": "Indicates whether vehicle should return to start address or not. If not, it can end at any service activity."
                },
                "earliest_start": {
                    "type": "integer",
                    "format": "int64",
                    "description": "earliest start of vehicle at its start location"
                },
                "latest_end": {
                    "type": "integer",
                    "format": "int64",
                    "description": "latest end of vehicle at its end location"
                },
                "skills": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    },
                    "description": "array of skills"
                }
            }
        },
        "Address": {
            "type": "object",
            "properties": {
                "location_id": {
                    "type": "string",
                    "description": "Unique identifier of location"
                },
                "lon": {
                    "format": "double",
                    "type": "number",
                    "description": "longitude"
                },
                "lat": {
                    "format": "double",
                    "type": "number",
                    "description": "latitude"
                }
            }
        },
        "VehicleType": {
            "properties": {
                "type_id": {
                    "type": "string",
                    "description": "Unique identifier for the vehicle type"
                },
                "profile": {
                    "type": "string",
                    "description": "Profile of vehicle type",
                    "example": "car",
                    "enum": [
                        "car",
                        "bike",
                        "foot"
                    ]
                },
                "distance_dependent_costs": {
                    "type": "number",
                    "format": "double",
                    "description": "cost factor of distance"
                },
                "time_dependent_costs": {
                    "type": "number",
                    "format": "double",
                    "description": "cost factor of time"
                },
                "capacity": {
                    "type" : "array",
                    "description" : "array of capacity dimensions",
                    "items": {
                        "type": "integer",
                        "format": "int32"
                    }
                }
            }
        },
        "Service": {
            "properties": {
                "id": {
                    "type": "string",
                    "description": "Unique identifier of service"
                },
                "type": {
                    "type": "string",
                    "description": "type of service",
                    "enum": [
                        "service"
                    ]
                },
                "name": {
                    "type": "string",
                    "description": "name of service"
                },
                "address": {
                    "$ref": "#/definitions/Address"
                },
                "duration": {
                    "type": "integer",
                    "format": "int64",
                    "description": "duration of service, i.e. time in ms the corresponding activity takes"
                },
                "time_windows": {
                    "type": "array",
                    "items": {
                        "$ref": "#/definitions/TimeWindow"
                    },
                    "description": "array of time windows. currently, only a single time window is allowed"
                },
                "size": {
                    "type" : "array",
                    "description" : "array of capacity dimensions",
                    "items": {
                        "type": "integer",
                        "format": "int32"
                    }
                },
                "required_skills": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    },
                    "description": "array of required skills"
                }

            }
        },
        "Shipment": {
            "type": "object",
            "properties": {
                "id": {
                    "type": "string",
                    "description": "Unique identifier of service"
                },
                "name": {
                    "type": "string",
                    "description": "name of shipment"
                },
                "pickup" : {
                    "$ref": "#/definitions/Stop"
                },
                "delivery" : {
                    "$ref": "#/definitions/Stop"
                },
                "size": {
                    "type" : "array",
                    "description" : "array of capacity dimensions",
                    "items": {
                        "type": "integer",
                        "format": "int32"
                    }
                },
                "required_skills": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    },
                    "description": "array of required skills"
                }
            }
        },
        "Stop": {
            "properties": {
                "address": {
                    "$ref": "#/definitions/Address"
                },
                "duration": {
                    "type": "integer",
                    "format": "int64",
                    "description": "duration of stop, i.e. time in ms the corresponding activity takes"
                },
                "time_windows": {
                    "type": "array",
                    "items": {
                        "$ref": "#/definitions/TimeWindow"
                    },
                    "description": "array of time windows. currently, only a single time window is allowed"
                }
            }
        },
        "TimeWindow": {
            "properties": {
                "earliest": {
                    "type": "integer",
                    "format": "int64",
                    "description": "earliest start time of corresponding activity"
                },
                "latest": {
                    "type": "integer",
                    "format": "int64",
                    "description": "latest start time of corresponding activity"
                }
            }
        },
        "LargeResponse": {
            "properties": {
                "job_id": {
                    "type": "string",
                    "description": "unique identify of job - which you get when posting your request to the large problem solver"
                },
                "status": {
                    "type": "string",
                    "enum": [
                        "waiting_in_queue",
                        "processing",
                        "finished"
                    ],
                    "description": "indicates the current status of the job"
                },
                "waiting_in_queue": {
                    "type": "integer",
                    "format": "int64",
                    "description": "waiting time in ms"
                },
                "processing_time": {
                    "type": "integer",
                    "format": "int64",
                    "description": "processing time in ms. if job is still waiting in queue, processing_time is 0"
                },
                "solution": {
                    "$ref": "#/definitions/Solution",
                    "description": "the solution. only available if status field indicates finished"
                }
            }
        },
        "Solution": {
            "properties": {
                "costs": {
                    "type": "integer",
                    "format": "int32",
                    "description": "overall costs of solution"
                },
                "distance": {
                    "type": "integer",
                    "format": "int32",
                    "description": "overall travel distance in meters"
                },
                "time": {
                    "type": "integer",
                    "format": "int64",
                    "description": "overall travel time in ms"
                },
                "no_unassigned": {
                    "type": "integer",
                    "format": "int32",
                    "description": "number of jobs that could not be assigned to final solution"
                },
                "routes": {
                    "type": "array",
                    "description": "An array of routes",
                    "items": {
                        "$ref": "#/definitions/Route"
                    }
                },
                "unassigned": {
                    "type": "object",
                    "properties": {
                        "services": {
                            "type": "array",
                            "description": "An array of ids of unassigned services",
                            "items": {
                                "type": "string",
                                "description": "id of unassigned service"
                            }
                        },
                        "shipments": {
                            "type": "array",
                            "description": "An array of ids of unassigned shipments",
                            "items": {
                                "type": "string",
                                "description": "id of unassigned shipments"
                            }
                        }
                    }
                }
            }
        },
        "Route": {
            "properties": {
                "vehicle_id": {
                    "type": "string",
                    "description": "id of vehicle that operates route"
                },
                "activities": {
                    "type": "array",
                    "description": "array of activities",
                    "items": {
                        "$ref": "#/definitions/Activity"
                    }
                }
            }
        },
        "Activity": {
            "properties": {
                "type": {
                    "type": "string",
                    "description": "type of activity",
                    "enum": [
                        "start",
                        "end",
                        "service"
                    ]
                },
                "id": {
                    "type": "string",
                    "description": "id referring to the underlying service or shipment, i.e. the shipment or service this activity belongs to"
                },
                "location_id": {
                    "type": "string",
                    "description": "id that refers to address"
                },
                "arr_time": {
                    "type": "integer",
                    "format": "int64",
                    "description": "arrival time at this activity in ms"
                },
                "end_time": {
                    "type": "integer",
                    "format": "int64",
                    "description": "end time of and thus departure time at this activity"
                }
            }
        }
    }
}