openapi: 3.2.0 info: title: Tour Planning API v3 Synchronous API description: The HERE Tour Planning API enables you to dynamically optimize routes for multiple vehicles visiting a set of locations, considering real-life constraints such as limited vehicle capacity and delivery time windows. version: 3.61.1 termsOfService: https://developer.here.com/terms-and-conditions license: name: HERE Documentation License url: https://legal.here.com/en-gb/terms/documentation-license servers: - url: https://tourplanning.hereapi.com/v3 description: Production environment base url. security: - Bearer: [] - ApiKey: [] tags: - name: Synchronous description: 'Endpoints that support synchronous request flows, allowing for immediate processing and responses to API requests.' paths: /problems: post: summary: Submit a Vehicle Routing Problem to solve it synchronously description: 'Solve a vehicle routing problem synchronously by optimizing vehicle routes and schedules for jobs (deliveries or pickups) from a depot, including constraints like vehicle capacity, job demand, time windows, and required skills.' tags: - Synchronous security: - ApiKey: [] - Bearer: [] parameters: - name: X-Request-Id in: header description: User-provided token that can be used to trace a request or a group of requests sent to the service. required: false style: simple explode: false schema: type: string example: 8230d7ad-3f1c-4191-a8dd-f3c42026da89 responses: '200': description: The solution to the vehicle routing problem (VRP) has been successfully calculated. content: application/json: schema: $ref: '#/components/schemas/Solution' headers: X-Correlation-Id: $ref: '#/components/headers/X-Correlation-Id' X-Request-Id: $ref: '#/components/headers/X-Request-Id' '400': description: The input parameters or configuration settings for the vehicle routing problem are invalid or incomplete. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' headers: X-Correlation-Id: $ref: '#/components/headers/X-Correlation-Id' X-Request-Id: $ref: '#/components/headers/X-Request-Id' '401': $ref: '#/components/responses/UnauthenticatedErrorResponse' '403': $ref: '#/components/responses/ForbiddenErrorResponse' '429': $ref: '#/components/responses/TooManyRequestsResponse' '500': $ref: '#/components/responses/ServerErrorResponse' requestBody: content: application/json: schema: $ref: '#/components/schemas/Problem' description: "[Detailed information](https://docs.here.com/tour-planning/docs/problem) necessary to compute optimized routes, encompassing fleet configuration, including \nvehicle types, profiles, costs, shifts, and capacity, as well as a plan detailing the jobs to be completed.\n" required: true operationId: postProblems x-operation-id-source: derived components: schemas: StopConfiguration: description: '**ALPHA** Configures how stops are created. Specifies how multiple jobs located close to each other can be grouped into a single stop.' properties: limits: $ref: '#/components/schemas/StopConfigurationLimits' profile: allOf: - $ref: '#/components/schemas/ProfileName' description: '**ALPHA** The vehicle profile to be used for calculating intra stop distances and durations. If its not set then the main vehicle profile is used for calculating intra stop metrics.' required: - profile type: object x-maturity: alpha ChargingStation: description: '**ALPHA** Specifies a shared place where vehicle can recharge.' example: id: recharge1 location: lat: 52.5256 lng: 13.4542 vehicleTypeToDuration: vehicle1: 300 properties: id: allOf: - $ref: '#/components/schemas/Id' description: Represents the unique ID of a charging station. example: recharge1 location: $ref: '#/components/schemas/RoutingLocation' tag: $ref: '#/components/schemas/PlaceTag' times: $ref: '#/components/schemas/TimeWindows' vehicleTypeToDuration: additionalProperties: $ref: '#/components/schemas/Duration' description: 'A mapping from vehicle type ID to the charging duration (in seconds) at this station. For distance-based charging, this duration should represent the time needed to fully charge the vehicle. For consumption-based charging, it should represent the time needed to charge the vehicle from minCharge to maxCharge.' example: vehicle1: 300 minProperties: 1 type: object required: - id - location - vehicleTypeToDuration type: object x-maturity: alpha VehicleIds: description: 'List of available vehicles. Can be used to assign individual vehicle to the tour. In other case `amount` property should be used. Each identifier must be unique across all vehicle types. Avoid assigning real-life identifiers, such as vehicle license plate as the `id` of a vehicle. Should not be the same as an autogenerated id of another type. E.g. if ''vehicle'' is used for one type then the name ''vehicle_1'' cannot be used for another type, otherwise the relations could not be satisfied.' example: - vehicle1_1 items: $ref: '#/components/schemas/Id' maxItems: 350 minItems: 1 type: array uniqueItems: true AvoidTruckRoadType: description: 'A truck road type identifier that routes will avoid going through. A truck road type identifier is associated with roads that have additional regulations applied by local administration for traversal by heavy vehicles like trucks. For example, the BK Bearing Class regulations in Sweden, and ET categories in Mexico. Identifiers for supported truck road types are specified at HERE Map Content [TruckRoadType](https://developer.here.com/documentation/here-map-content/dev_guide/topics_schema/truckroadtypeattribute.truckroadtype.html)' enum: - TRUCK_ROAD_TYPE_UNKNOWN - ET4 - ET2 - A4 - A2 - B4 - B2 - C - D - BK1 - BK2 - BK3 - BK4 example: A4 type: string Traffic: description: Traffic specific parameters. properties: mode: description: 'Defines what traffic data should be used for route shape and travel duration calculation. - `default`: Traffic data is considered. - `disabled`: All traffic data, including long term closures, is ignored.' enum: - default - disabled example: disabled type: string required: - mode type: object MaxTimeOnVehicle: description: 'The maximum amount of time in seconds the job is allowed to stay on the vehicle. Constrains the maximum time the job can be on the vehicle in the solution. This constraint is calculated as follows: * For jobs with pickups and deliveries, this is the duration from the first pickup activity to the arrival at the last delivery activity. * For jobs with only one delivery, the duration is counted from either the departure activity location or the previous reload activity. * For jobs with only pickups, the duration is counted until the arrival activity or the next reload. * If the shift does not have an end, the duration is counted until the end of the last activity in the tour. * The duration of the first loading and the last unloading activity is excluded from that time. For a practical application of this constraint, see [Plan employee transportation](https://docs.here.com/tour-planning/docs/employee-pickup-dropoff).' example: 180 format: int64 maximum: 604800 minimum: 0 type: integer TaxiProfile: description: 'Route calculation for taxis. This profile takes into account taxi restricted streets as well as streets reserved for exclusive taxi access. It does not, however, consider exclusive lanes in otherwise shared streets. Also, the taxi exclusive streets are used only if either the origin or destination are on them. The `departureTime` property allows to specify a custom date-time for which `traffic optimization` in routing calculations shall be performed. See `fleet.traffic` for details.' properties: avoid: $ref: '#/components/schemas/AvoidRoutes' departureTime: $ref: '#/components/schemas/DateAndTime' exclude: $ref: '#/components/schemas/Exclude' ignoreRouteViolations: $ref: '#/components/schemas/IgnoreRouteViolations' matrix: $ref: '#/components/schemas/Matrix' matrixId: $ref: '#/components/schemas/MatrixId' name: $ref: '#/components/schemas/ProfileName' options: $ref: '#/components/schemas/TaxiOptions' traffic: $ref: '#/components/schemas/Traffic' type: enum: - taxi example: taxi type: string violationMapping: $ref: '#/components/schemas/ViolationMapping' required: - name - type type: object AdvancedObjective: discriminator: mapping: balanceActivities: '#/components/schemas/BalanceActivities' balanceDistance: '#/components/schemas/BalanceDistance' balanceDuration: '#/components/schemas/BalanceDuration' balanceMaxLoad: '#/components/schemas/BalanceMaxLoad' maximizePriorityJobs: '#/components/schemas/MaximizePriorityJobs' maximizeTerritoryJobs: '#/components/schemas/MaximizeTerritoryJobs' maximizeTours: '#/components/schemas/MaximizeTours' minimizeCost: '#/components/schemas/MinimizeCost' minimizeDistance: '#/components/schemas/MinimizeDistance' minimizeDuration: '#/components/schemas/MinimizeDuration' minimizeSoftTimeWindowViolations: '#/components/schemas/MinimizeSoftTimeWindowViolations' minimizeTourOverlap: '#/components/schemas/MinimizeTourOverlap' minimizeTours: '#/components/schemas/MinimizeTours' minimizeUnassigned: '#/components/schemas/MinimizeUnassigned' optimizeTaskOrder: '#/components/schemas/OptimizeTaskOrder' optimizeTaskPosition: '#/components/schemas/OptimizeTaskPosition' serveInClusters: '#/components/schemas/ServeInClusters' tieBreak: '#/components/schemas/TieBreak' tourOrder: '#/components/schemas/TourOrder' visuallyAppealingTours: '#/components/schemas/VisuallyAppealingTours' propertyName: type oneOf: - $ref: '#/components/schemas/MinimizeUnassigned' - $ref: '#/components/schemas/MinimizeCost' - $ref: '#/components/schemas/MinimizeTours' - $ref: '#/components/schemas/MaximizeTours' - $ref: '#/components/schemas/MinimizeDistance' - $ref: '#/components/schemas/MinimizeDuration' - $ref: '#/components/schemas/BalanceMaxLoad' - $ref: '#/components/schemas/BalanceActivities' - $ref: '#/components/schemas/BalanceDistance' - $ref: '#/components/schemas/BalanceDuration' - $ref: '#/components/schemas/MaximizePriorityJobs' - $ref: '#/components/schemas/TourOrder' - $ref: '#/components/schemas/MaximizeTerritoryJobs' - $ref: '#/components/schemas/VisuallyAppealingTours' - $ref: '#/components/schemas/OptimizeTaskPosition' - $ref: '#/components/schemas/MinimizeTourOverlap' - $ref: '#/components/schemas/ServeInClusters' - $ref: '#/components/schemas/TieBreak' - $ref: '#/components/schemas/MinimizeSoftTimeWindowViolations' - $ref: '#/components/schemas/OptimizeTaskOrder' x-maturity: alpha DbscanStopConfig: properties: maxDiameter: description: The maximum allowed distance between two activities in the stop. example: 120 format: double maximum: 1000 minimum: 0 type: number maxDistanceToNeighbor: description: Defines the maximum distance in meters between an activity and its closest neighbor in the cluster. example: 50 format: double maximum: 500 minimum: 0 type: number minNeighborCount: default: 3 description: The number of close neighbors an activity must have to be considered as dense by DBSCAN. example: 3 maximum: 15 minimum: 2 type: integer profile: allOf: - $ref: '#/components/schemas/ProfileName' description: 'Deprecated, please use stopProfile instead The vehicle profile to be used for calculating distances between activities.' type: enum: - dbscan example: dbscan type: string required: - maxDistanceToNeighbor - type type: object x-maturity: alpha Interval: description: Represents an activity interval. properties: arrival: $ref: '#/components/schemas/DateAndTime' end: $ref: '#/components/schemas/DateAndTime' start: $ref: '#/components/schemas/DateAndTime' required: - start - end type: object JobCostRate: description: '**ALPHA** A per-job cost rate. Used as the base rate in per-job cost calculation and as the override rate for specific job-vehicle pairs.' example: 4 format: double maximum: 100000 minimum: 0 type: number x-maturity: alpha Group: description: '**BETA** Represents a [collection of jobs](https://docs.here.com/tour-planning/docs/group-jobs) linked by criteria such as geographic proximity, delivery windows, or product types. Jobs in the same group are assigned to one vehicle and completed sequentially before moving on to other jobs or groups.' properties: id: allOf: - $ref: '#/components/schemas/Id' description: 'Represents the unique ID of a [job group](https://docs.here.com/tour-planning/docs/group-jobs). Assign this ID at the `job.places` level to include the job in the corresponding group.' example: group1 placement: default: strict description: 'Group placement mode: "strict" (consecutive) or "flexible" (anywhere in tour).' enum: - strict - flexible example: strict type: string pudos: description: 'The list of pick-up and drop-off points (PUDOs). These locations are designated for the collection and delivery of passengers or goods.' items: $ref: '#/components/schemas/Pudo' maxItems: 2 minItems: 1 type: array required: - id type: object x-maturity: beta VisuallyAppealingTours: description: '**ALPHA** An objective to produce a more visually appealing tours in contrast to cost/balancing considerations' properties: maxClusterRadius: description: "Specifies a radius in meters in which job locations are clustered. Jobs in the same cluster are served consecutively before moving on the next cluster.\nSuitable values for the parameter depend on the job distribution and need to be tuned until satisfactory results are achieved.\n This parameter will be ignored if the following features are present in the problem:\n * time windows\n * breaks\n * skills\n * reloads\n * tour order\n * mixing restrictions\n * max time on vehicle\n * relations\n * group jobs\n * territory constraint\n * more than one vehicle\n The parameter is not related to the _clustering feature_." example: 300 format: int64 maximum: 100000 minimum: 10 type: integer tolerance: description: A tolerance specifies how much objective values should differ in order to be considered as not-equal example: 0.1 format: double maximum: 1 minimum: 0 type: number type: enum: - visuallyAppealingTours example: visuallyAppealingTours type: string weight: description: 'A weight parameter specifies trade off between visual appealing aspect and routing considerations. The value should be in the range [0; 1] and defines how much visual aspect dominates over routing.' example: 0.5 format: double maximum: 1 minimum: 0 type: number required: - type type: object x-maturity: alpha OptimizeTourCount: description: Optimizes the number of vehicles used in the solution. The action parameter determines whether to maximize or minimize the vehicle count properties: action: enum: - maximize - minimize example: minimize type: string type: enum: - optimizeTourCount example: optimizeTourCount type: string required: - action - type type: object TourOrder: deprecated: true description: '**ALPHA** Deprecated, use OptimizeTaskPosition instead. An objective to control order of job activities in the tour.' properties: isConstrained: description: If the property is set to true, then order is enforced as hard constraint. example: false type: boolean type: enum: - tourOrder example: tourOrder type: string required: - isConstrained - type type: object x-maturity: alpha MinimizeSoftTimeWindowViolations: description: '**ALPHA** An objective to minimize soft time window violations.' properties: type: enum: - minimizeSoftTimeWindowViolations example: minimizeSoftTimeWindowViolations type: string required: - type type: object x-maturity: alpha Activity: description: 'An activity is defined as a planned task to be performed at a specific location and time within a stop on a tour. Each activity has properties like `jobId`, `type`, `location`, `time`, and `jobTag`. The `type` property specifies the activity type, for example, `pickup` or `delivery`. **Note**: If you omit location or time from the activity definition, then the service uses the values defined for the parent stop instead.' properties: compartment: allOf: - $ref: '#/components/schemas/Id' description: '**ALPHA** Compartment where the activity load is allocated, empty if compartments are not used' x-maturity: alpha jobId: allOf: - $ref: '#/components/schemas/Id' description: 'A unique identifier for a job, provided when submitting a problem request. It allows tracking and retrieval of specific job-related information. **Note**: Do not include any personal information within the `JobId`. For example, avoid using a license plate number that could be used to identify the driver.' jobTag: allOf: - $ref: '#/components/schemas/PlaceTag' description: 'Optionally, allows adding extra information related to a specific job for easier identification or categorization. For example, you could tag jobs based on the time of day they need to be delivered, such as `"morning-delivery"`. **Note**: Do not include any personal information within the `JobTag`. For example, avoid using a license plate number that could be used to identify the driver.' location: $ref: '#/components/schemas/Location' notices: description: 'A list of notices that provide additional information about the request. For example, these notices might include suggestions on how to improve the problem formulation.' items: $ref: '#/components/schemas/Notice' type: array time: $ref: '#/components/schemas/Interval' type: $ref: '#/components/schemas/ActivityType' required: - jobId - type type: object ScooterOptions: description: Specifies scooter profile options. properties: allowHighway: default: false description: 'Specifies whether routing calculation should take highways into account. When this parameter isn''t provided, then by default highways would be avoided. If the avoid feature `motorway` is provided, then highways would be avoided, even if `allowHighway` is set to `true`.' example: false type: boolean speedCap: $ref: '#/components/schemas/SpeedCap' type: object Problem: description: 'A [problem](https://docs.here.com/tour-planning/docs/problem) JSON file that defines the fleet, jobs, and configuration for optimizing tours, which is passed synchronously or asynchronously to the HERE Tour Planning API to create an optimized tour plan.' properties: advancedObjectives: description: '**ALPHA** [Extended objectives](https://docs.here.com/tour-planning/docs/objectives#advanced-objectives) that allow for more complex and tailored optimization strategies beyond basic goals like minimizing tour distance or cost. **Note**: This is an experimental feature under development. To enable this feature, add the `advancedObjectives` flag to the `experimentalFeatures` configuration in the problem.' example: - - type: minimizeUnassigned - - type: minimizeCost items: $ref: '#/components/schemas/MultiObjective' maxItems: 8 minItems: 1 type: array x-maturity: alpha configuration: $ref: '#/components/schemas/Configuration' fleet: $ref: '#/components/schemas/Fleet' objectives: description: '[Objectives](https://docs.here.com/tour-planning/docs/objectives#default-objectives) that guide tour optimization by setting goals like minimizing distance, duration, costs, or unassigned jobs, and can be combined hierarchically to meet specific criteria.' example: - type: minimizeUnassigned - type: minimizeCost items: $ref: '#/components/schemas/Objective' maxItems: 6 minItems: 1 type: array plan: $ref: '#/components/schemas/Plan' required: - plan - fleet type: object Job: description: 'Represents a job to be served by any vehicle, taking into account specific properties such as location, duration, demand, time windows, skills, and so on. A job can be one of the following types: `pickup` (picking something along the route and bringing it to the route''s end location, such as a depot), `delivery` (delivering something loaded at the beginning of the route), or mixed (picking and delivering along the route). For more information, see [Job](https://docs.here.com/tour-planning/docs/problem#job).' properties: category: $ref: '#/components/schemas/Category' costFactor: default: 1 description: '**ALPHA** Cost factor for per-job cost calculation. Defaults to 1.0. Represents the "quantity" for cost calculation (boxes, parcels, items - opaque to solver).' example: 1 format: double minimum: 0 type: number x-maturity: alpha customerId: allOf: - $ref: '#/components/schemas/Id' description: 'An optional property used with the service duration clustering feature (`plan.clustering`). When service duration clustering is enabled and this property is present, jobs with the same `customerId` value are grouped together and assigned to the same stop if feasible, where they are served simultaneously as separate activities. Jobs with different `customerId` values are treated as separate clusters and are not grouped together, even if their other attributes match. **Note**: This property applies only to service duration clustering, not to geographic clustering (`stopConfig` with the `clusterNearby` experimental feature). Avoid referencing any sensitive or personal information, such as names, addresses, or delivery details, as part of the `customerId`. For more information, see [Clustering](https://docs.here.com/tour-planning/docs/problem#clustering).' example: 4bbc206d-1583-4266-bac9-d1580f412ac0 id: allOf: - $ref: '#/components/schemas/Id' description: 'A unique identifier for a job, provided when submitting a problem request. It allows tracking and retrieval of specific job-related information. Do not include any personal information within the `JobId`. For example, avoid using a license plate number that could be used to identify the driver.' example: 4bbc206d-1583-4266-bac9-d1580f412ac0 maxTimeOnVehicle: $ref: '#/components/schemas/MaxTimeOnVehicle' priority: default: 5 description: 'Specifies the priority of the job with `1` for highest priority jobs, `2`-`4` for high to medium priority, and `5` for normal jobs. Jobs without any priority are treated as jobs with priority `5`. The priority setting optimizes route planning by ensuring that more critical jobs are included in the tour planning ahead of less urgent ones, even when not all jobs can be completed due to constraints like vehicle capacity. **BETA** Specifying more than 2 different levels of priority among all jobs is experimental. For more information, see [Prioritize jobs](https://docs.here.com/tour-planning/docs/priority).' example: 1 maximum: 5 minimum: 1 type: integer skills: $ref: '#/components/schemas/Skills' tasks: $ref: '#/components/schemas/JobTasks' required: - id - tasks type: object TimeWindowsViolations: description: '**ALPHA** Indicates the total number and the sum of seconds by which all [soft time windows](https://docs.here.com/tour-planning/docs/soft-time-windows) were violated. Violations are instances where the planned arrival times at specific locations do not comply with the predefined hard constraints allocated for those stops.' properties: count: description: The total number of times soft time windows were violated. example: 1 format: double type: number total: description: The total sum of seconds by which soft time windows were violated. example: 10 format: double type: number required: - count - total type: object x-maturity: alpha Notice: description: 'A notice provides additional information about the request, such as hints on how to improve the problem formulation. This information can help you understand potential issues and make necessary adjustments to optimize your request.' properties: action: description: Provides specific actions to address the issue or improve the problem formulation. example: Check whether the vehicle types use the correct profiles. type: string code: description: 'A unique code for each type of notice to ensure clear identification and differentiation. | Code | Reason | | ---------------------------------------------- | ------------------------------------------------------------------ | | `unusedVehicleProfile` | Vehicle profile is not used | | `duplicatedVehicleProfile` | Vehicle profile is duplicated | | `minimizeUnassignedNotAtHighestPriority` | `minimizeUnassigned` objective is not at highest priority | | `noVehicleWithSkillsForJob` | No vehicle type matching skills of job | | `unreachableLocation` | Location unreachable | | `pudoTimeWindowOutsideOfShifts` | Pudo time window is outside of vehicle''s shift time range | | `deprecatedField` | Specified field is deprecated | | `allJobsHaveTheSamePriority` | All jobs have the same priority | | `allJobsHaveTheSameCategory` | All jobs have the same category | | `allJobsHaveTheSameCustomerId` | All jobs have the same customerId | | `allJobPlacesHaveTheSameGroup` | All job places have the same group | | `allJobPlacesHaveTheSameGroupWithManyVehicles` | All job places have the same group, only one vehicle will serve it | | `allJobTasksHaveTheSamePosition` | All jobs tasks have the same position | | `allJobTasksHaveTheSameOrder` | All job tasks have the same order | | `unusedVehicleSkills` | Vehicle profiles have skills not used by any job | | `allJobsAndVehiclesHaveTheSameSkills` | All jobs and vehicle have the same skills | | `jobHasIncorrectTimeWindows` | Job has time window(s) not supported by any vehicle | | `routeDetailsUnauthorized` | Unauthorized usage of route details | | `routeDetailsFailure` | Could not get route details | ! `allPudoTimeWindowsOutsideOfShifts` | All pudo time windows are outside of vehicle''s shift time range | ! `unusedStopConfigurationProfile` | stopConfiguration is defined but its not used | ! `deprecatedStopConfig` | stopConfig is used but it is deprecated | ! `unknownParkingId` | parking referenced by the job is not defined in the problem | ! `costFactorWithoutPerJob` | costFactor is set while cost per job is not configured |' example: unusedVehicleProfile type: string link: description: Provides a link to the page with additional details about the notice. example: https://docs.here.com/tour-planning/docs/ type: string title: description: A human-readable description of the notice. example: Vehicle profile 'truck_1' is not used by any vehicle type. type: string required: - code - title type: object Penalty: description: '**ALPHA** Specifies the penalty function applied when the preferred (soft) time window is violated. The penalty score is an abstract numeric value used by the optimization algorithm to evaluate solutions - it does not directly affect cost or duration parameters. The system minimizes penalty scores by scheduling activities as close to preferred time boundaries as possible. Linear penalty is applied by default.' discriminator: mapping: linear: '#/components/schemas/LinearPenalty' quadratic: '#/components/schemas/QuadraticPenalty' propertyName: type oneOf: - $ref: '#/components/schemas/LinearPenalty' - $ref: '#/components/schemas/QuadraticPenalty' x-maturity: alpha Profile: discriminator: mapping: bicycle: '#/components/schemas/BicycleProfile' bus: '#/components/schemas/BusProfile' car: '#/components/schemas/CarProfile' pedestrian: '#/components/schemas/PedestrianProfile' privateBus: '#/components/schemas/PrivateBusProfile' scooter: '#/components/schemas/ScooterProfile' taxi: '#/components/schemas/TaxiProfile' truck: '#/components/schemas/TruckProfile' propertyName: type oneOf: - $ref: '#/components/schemas/ScooterProfile' - $ref: '#/components/schemas/BicycleProfile' - $ref: '#/components/schemas/PedestrianProfile' - $ref: '#/components/schemas/CarProfile' - $ref: '#/components/schemas/TruckProfile' - $ref: '#/components/schemas/BusProfile' - $ref: '#/components/schemas/PrivateBusProfile' - $ref: '#/components/schemas/TaxiProfile' BoundingBoxArea: description: A bounding box defined by two longitudes and two latitudes. properties: east: description: Longitude in WGS-84 degrees of the eastern boundary of the box example: 30 format: double maximum: 180 minimum: -180 type: number north: description: Latitude in WGS-84 degrees of the northern boundary of the box. example: 30 format: double maximum: 90 minimum: -90 type: number south: description: Latitude in WGS-84 degrees of the southern boundary of the box. example: 30 format: double maximum: 90 minimum: -90 type: number type: enum: - boundingBox example: boundingBox type: string west: description: Longitude in WGS-84 degrees of the western boundary of the box. example: 30 format: double maximum: 180 minimum: -180 type: number required: - north - south - west - east - type type: object MinimizeDuration: description: An objective to minimize total duration calculated as the sum of all tour durations. properties: type: enum: - minimizeDuration example: minimizeDuration type: string required: - type type: object MinimizeUnassigned: description: Minimizes the number of unassigned jobs properties: type: enum: - minimizeUnassigned example: minimizeUnassigned type: string required: - type type: object JobPlace: description: 'Refers to a specific location where one or more pickup or delivery activities occur. A place is defined by geographical coordinates (latitude and longitude) and might include additional details like duration (service time), job time window, group information for the activity, skills, territories, and more. Each job task can have up to three places, and at least one place must be specified for each task.' properties: duration: $ref: '#/components/schemas/Duration' groupId: allOf: - $ref: '#/components/schemas/Id' description: 'An optional parameter specifying the ID of the group to which the job belongs. Jobs with the same `groupId` are served by a single vehicle only (one group cannot be shared between multiple vehicles, but a single vehicle can serve multiple groups). Depending on your business objctives, you can determine whether the vehicle must serve all jobs belonging to a particular group before moving to the next one or whether it can interleave jobs from different groups if it makes the tour more efficient. Jobs which do not belong to any group, reloads, and breaks with a location cannot interrupt a group, but they can be served between individual groups. Breaks without locations can interrupt a group. For more information, see [Assign jobs to groups](https://docs.here.com/tour-planning/docs/group-jobs).' example: group1 houseKeyId: allOf: - $ref: '#/components/schemas/Id' description: '**ALPHA** Specifies id of the house key, used for multi-delivery and multi-pickup scenarios at the same location. A `houseKeyId` allows controlling the total job duration of multiple jobs served at the same customer location. For example, in case multiple jobs with the same `houseKeyId` are served together, the maximum duration of the individual jobs is applied as the total duration for this set of jobs. **Note**: This is an experimental feature under development. To enable it, add `houseKeys` flag to `experimentalFeatures` configuration in the problem. For more information, see [Allow customer-based service durations](https://docs.here.com/tour-planning/docs/house-key).' example: house_key_1 x-maturity: alpha location: $ref: '#/components/schemas/RoutingLocation' parkingIds: description: '**ALPHA** Specifies IDs of the parking where the vehicle can be parked while performing the job at this place. References parking options defined in the `shared.parking` array to specify the parking with specific duration available for that particular job. Parking duration represents only the time required for parking-related activities (such as finding a spot, maneuvering, and securing the vehicle). It does not represent the total time the vehicle remains at the location. **Note**: This is an experimental feature under development. To enable it, add `parkingIds` flag to `experimentalFeatures` configuration in the problem. For more information, see [Configure location-specific parking durations](https://docs.here.com/tour-planning/docs/location-specific-parking).' example: - parking1 items: $ref: '#/components/schemas/Id' maxItems: 1 minItems: 1 type: array x-maturity: alpha tag: $ref: '#/components/schemas/PlaceTag' territoryIds: description: 'Specifies the territory assigned to this job place, defining spatial restrictions on the jobs a vehicle is allowed or preferred to take. For more information, see [Optimize tours by territories](https://docs.here.com/tour-planning/docs/territory).' items: $ref: '#/components/schemas/Id' maxItems: 1 minItems: 1 type: array timeWindows: items: $ref: '#/components/schemas/SoftTimeWindow' maxItems: 4 minItems: 0 type: array times: $ref: '#/components/schemas/TimeWindows' required: - location - duration type: object Relation: description: 'Defines how specific jobs are related to each other and how they should be completed by a specific vehicle (defined by the `${vehicleType}_${sequenceIndex}` pattern). The primary application for job relation is [**tour replanning**](https://docs.here.com/tour-planning/docs/relations).' example: jobs: - departure - 4bbc206d-1583-4266-bac9-d1580f412ac0 - 4bbc206d-1583-4266-bac9-d1580f412ac0 - arrival shiftIndex: 0 type: sequence vehicleId: vehicle1_1 properties: jobs: description: "Job IDs that represent the sequence or order in which the connected jobs are to be completed by a vehicle.\nIn addition to Job IDs, you can optionally provide the following activity names to enforce further constraints within a specific relation:\n * `departure`: This activity marks the beginning of the sequence and prevents other jobs from\n being scheduled before the departure activity. It must always be the first item in the `jobs` array, if included.\n * `break`: If included, this activity enforces a scheduled pause for the vehicle during its route.\n * `arrival`: This activity marks the end of the sequence and prevents other jobs from\n being scheduled after the arrival activity. It must always be the last item in the `jobs` array if included." items: $ref: '#/components/schemas/Id' maxItems: 1000 minItems: 1 type: array shiftIndex: $ref: '#/components/schemas/ShiftIndex' type: $ref: '#/components/schemas/RelationType' vehicleId: $ref: '#/components/schemas/Id' required: - type - jobs - vehicleId type: object Matrix: description: '**ALPHA** Routing matrix for vehicle profile. The matrix has to contain 2 flat arrays, `travelTimes` and `distances`. Each array represents a 2D matrix where rows correspond to `origins` and columns to `destinations`. The `k`-th position in the array corresponds to the `(i, j)` position in the matrix defined by the following relationship: ```nocompile k = num_destinations * i + j, ``` where `i` is origin and `j` is destination. Important: The order of elements in both arrays is crucial. Data should be arranged in the same order as in `origins` array. If there is no route between `i` and `j` or a route violates some options, another `errorCodes` array should be included with a detailed error code for each pair of positions.' properties: distances: description: Corresponds to 2D matrix of distances (in meters). items: format: int32 type: integer maxItems: 1000000 minItems: 4 type: array errorCodes: description: 'Contains error codes for entries in the matrix if there is no route between `i` and `j`. Optional, no need to be added if all routes exist. | Value | Reason | |-------|------------------------------------------------------------------------------------------------| | 0 | No error, a route is available | | 1 | No route between the origin and destination exists | | 2 | No valid starting or ending point for the route between the origin and destination locations | | 3 | The route between the origin and destination exists but includes violations that could make it potentially unusable | | 4 | The origin and destination locations are either just inside the acceptable range or completely outside the allowed area. Because of this, there are no valid route start or end points for origin and destination locations | | 99 | Unknown error (for debugging and handling unexpected situations) |' example: - 0 - 1 - 2 - 3 items: format: int32 type: integer maxItems: 1000000 minItems: 4 type: array origins: description: An ordered list of origins used in the routing matrix items: $ref: '#/components/schemas/MatrixOrigin' maxItems: 1000 minItems: 2 type: array travelTimes: description: Corresponds to 2D matrix of travelTimes (in seconds). items: format: int32 type: integer maxItems: 1000000 minItems: 4 type: array required: - origins - travelTimes - distances type: object x-maturity: alpha BoundedSumStrategy: description: 'Ensures the total duration of a job cluster is the sum of individual job durations, capped at a maximum limit. This strategy is useful for grouping similar jobs without exceeding a specified service time.' example: maximum: 3600 type: boundedSumStrategy properties: maximum: description: The upper limit for the total duration all jobs in a cluster, expressed in seconds. format: int64 type: integer type: enum: - boundedSumStrategy example: boundedSumStrategy type: string required: - maximum - type type: object Coordinate: example: lat: 52.53787 lng: 13.40896 properties: lat: description: Latitude in WGS-84 degrees. format: double type: number lng: description: Longitude in WGS-84 degrees. format: double type: number required: - lat - lng type: object Solution: description: "Contains detailed information about how to efficiently solve a vehicle routing problem by completing a set of jobs with a fleet of vehicles. The solution includes the following elements:\n * **statistic**: Summary of total distance, duration, and cost.\n * **costs**: Total cost, considering distance, time, and fixed costs.\n * **tours**: Sequences of stops assigned to each vehicle.\n * **job assignments**: Jobs assigned to each vehicle in order.\n * **activities**: Actions at each stop, with start and end times.\n * **unassigned jobs**: Jobs that couldn't be assigned and reasons why.\n\nFor more information, see [Solution](https://docs.here.com/tour-planning/docs/solution)." properties: notices: description: 'A list of notices that provide additional information about the request. For example, these notices might include suggestions on how to improve the problem formulation.' items: $ref: '#/components/schemas/Notice' type: array statistic: $ref: '#/components/schemas/Statistic' tours: description: 'The [list of tours](https://docs.here.com/tour-planning/docs/solution#list-of-tours) in the response from the service after submitting a problem for solving. This list includes detailed information about each tour, such as the route, stops, activities at each stop, and more.' items: $ref: '#/components/schemas/Tour' type: array unassigned: description: 'List of jobs that could not be allocated to any vehicle, for example, when no vehicle has the required skills, the vehicle''s capacity is exceeded, or specific constraints (like time windows or territories) cannot be met. For more information on the possible reasons for unassigned jobs, see [Troubleshoot unassigned jobs](https://docs.here.com/tour-planning/docs/troubleshoot-unassigned-jobs).' items: $ref: '#/components/schemas/UnassignedJob' type: array required: - statistic type: object ViolationMappingOptionalField: description: "Defines how a specific violation attribute should be handled within a\nviolation mapping. Use:\n `include`: the violated restriction is added to a mapped\n category instead of causing a hard error code 3.\n\n `exclude`: the violated restriction is not added to a mapped\n category and still causes an error code 3. This is the default for\n height and grossWeight.\n\n `ignore`: the algorithm is not taking the restriction or\n property / attribute of the road into consideration.\n This is the default attribute for restrictions on bridge or time-dependent" enum: - include - exclude - ignore type: string HouseKeysFixedDurationStrategy: description: Sets the total duration to a fixed value, regardless of individual job durations. example: duration: 300 type: fixedDuration properties: duration: $ref: '#/components/schemas/Duration' description: The total duration in seconds. type: enum: - fixedDuration example: fixedDuration type: string required: - duration - type type: object x-maturity: alpha BalanceDistance: description: '**ALPHA** An objective to balance distance across all tours.' properties: options: $ref: '#/components/schemas/BalanceOptions' type: enum: - balanceDistance example: balanceDistance type: string required: - options - type type: object x-maturity: alpha VehicleBreak: description: 'A vehicle break time. It starts in the declared time window and can end after the time window (based on the duration). Either a rest time or a break can be specified.' properties: duration: $ref: '#/components/schemas/Duration' location: $ref: '#/components/schemas/RoutingLocation' policy: $ref: '#/components/schemas/VehicleBreakPolicy' times: $ref: '#/components/schemas/TimeWindows' required: - times - duration type: object MinimizeTourOverlap: description: '**ALPHA** An objective to produce less overlapping tours, that are more geographically separated and more compact' properties: alpha: description: 'A coefficient that controls the sensitivity of the termination criteria towards changes in this objective. Smaller values make the solver more sensitive to improvements and may result in longer run times. Default value is 0.014 when useRealDistance is set and 1.0 otherwise' example: 0.01 format: double maximum: 1 minimum: 1.0e-05 type: number tolerance: description: A tolerance specifies how much objective values should differ in order to be considered as not-equal example: 0.1 format: double maximum: 1 minimum: 0 type: number type: enum: - minimizeTourOverlap example: minimizeTourOverlap type: string useRealDistance: default: false description: 'Uses real street network distances instead of aerial distances, producing tours that conform to road topology and avoid splitting across obstacles like rivers or highways' example: false type: boolean required: - type type: object x-maturity: alpha UnassignedJob: description: Specifies an unassigned job and outlines [possible causes of unassignment](https://docs.here.com/tour-planning/docs/troubleshoot-unassigned-jobs). properties: jobId: $ref: '#/components/schemas/Id' reasons: description: 'A list of possible explanations for why a specific job may not have been assigned. | Code | Reason | | ------------------------------------ | ----------------------------------------------------------------- | | `NO_REASON_FOUND` | No reason found | | `SKILL_CONSTRAINT` | Cannot be assigned due to required skill | | `TIME_WINDOW_CONSTRAINT` | Cannot be assigned due to violation of time window | | `CAPACITY_CONSTRAINT` | Cannot be assigned due to capacity of vehicle | | `REACHABLE_CONSTRAINT` | Location unreachable | | `MAX_DISTANCE_CONSTRAINT` | Cannot be assigned due to max distance constraint of vehicle | | `SHIFT_TIME_CONSTRAINT` | Cannot be assigned due to shift time constraint of vehicle | | `LOCKING_CONSTRAINT` | Cannot be assigned due to relation lock | | `TOUR_ORDER_CONSTRAINT` | Cannot be assigned due to tour order constraint | | `MAX_STOPS_CONSTRAINT` | Cannot be assigned due to exceeding the maximum number of stops | | `MIN_STOPS_CONSTRAINT` | Cannot be assigned due to not reaching the minimum number of stops| | `BREAK_CONSTRAINT` | Break cannot be assigned | | `AREA_CONSTRAINT` | Cannot be assigned due to area constraint | | `TERRITORY_CONSTRAINT` | Cannot be assigned due to territory constraint | | `UNREACHABLE_IN_RELATION_CONSTRAINT` | Cannot be assigned due to relation constraint | | `MIXING_RESTRICTION_CONSTRAINT` | Cannot be assigned due to mixing restriction constraint | | `GROUP_CONSTRAINT` | Cannot be assigned due to group constraint | | `MAX_DRIVING_TIME_CONSTRAINT` | Cannot be assigned due to max driving time constraint | | `MAX_TIME_ON_VEHICLE_CONSTRAINT` | Cannot be assigned due to max time on vehicle constraint |' items: $ref: '#/components/schemas/UnassignedJobReason' minItems: 1 type: array required: - jobId - reasons type: object Category: description: 'Specifies a job category used in conjunction with vehicle mixing restrictions to prevent incompatible goods from being transported together. Categories are user-defined and can represent goods types such as `perishable`, `electronics`, `food`, `flammable`, etc. When mixing restrictions are configured on a vehicle shift, jobs with conflicting categories cannot be assigned to the same tour or sub-tour, depending on the restriction level. For more information, see [Define mixed load restrictions](https://docs.here.com/tour-planning/docs/mixing-restrictions).' example: food maxLength: 64 minLength: 1 pattern: ^[a-zA-Z0-9_-]+$ type: string VehicleFuel: description: 'Fuel parameters to be used for calculating consumption and related CO2 emission. These are not taken into account for optimization. **Note**: `speedFactor` parameter does not influence the fuel consumption and CO2 emission.' properties: additionalConsumption: description: Rate of fuel (in l/s for diesel, petrol & LPG, kg/s for CNG) consumed by the vehicle for any other reason additional to fuel consumption for speed. example: 1.8 format: double minimum: 0 type: number ascent: description: Rate of fuel consumed per meter rise in elevation (in l/m for diesel, petrol & LPG, kg/m for CNG). example: 0.1 format: double minimum: 0 type: number freeFlowSpeedTable: description: 'Function curve specifying consumption rate at a given speed. The format of the string is a comma-separated list of numbers, as follows: ```nocompile ,,,,...,, ``` where speed values are strictly increasing, non-negative integers in units of (m/s), and consumption values are non-negative floating point values. | Vehicle Type | Unit | | -------------------- | -------------------------------- | | Diesel, Petrol & LPG | l/m i.e., liters per meter | | CNG | kg/m i.e., kilograms per meter | The function is linearly interpolated between data points. For speeds less than `SPEED_0` the value of the function is `CONSUMPTION_0`, and for speeds greater than `SPEED_N` the value of the function is `CONSUMPTION_N`.' example: 0,0.00024,4,0.00024,10,0.00026,15,0.0002,19,0.00021,23,0.00024,26,0.00026,29,0.00026,32,0.0003,35,0.00034,38,0.00035 type: string trafficSpeedTable: description: 'Function curve specifying consumption rate at a given traffic-reduced speed on a flat stretch of road. The format of the string is a comma-separated list of numbers, as follows: ```nocompile ,,,,...,, ``` where speed values are strictly increasing, non-negative integers in units of (m/s), and consumption values are non-negative floating point values. | Vehicle Type | Unit | | -------------------- | -------------------------------- | | Diesel, Petrol & LPG | l/m i.e., liters per meter | | CNG | kg/m i.e., kilograms per meter | The function is linearly interpolated between data points. For speeds less than `SPEED_0` the value of the function is `CONSUMPTION_0`, and for speeds greater than `SPEED_N` the value of the function is `CONSUMPTION_N`.' example: 0,0.00024,4,0.00024,10,0.00026,15,0.0002,19,0.00021,23,0.00024,26,0.00026,29,0.00026,32,0.0003,35,0.00034,38,0.00035 type: string type: description: 'Vehicle fuel type (diesel, petrol, lpg, etc.) required for calculation of consumption and CO2 emission. ' example: petrol type: string x-extensible-enum: - diesel - petrol - lpg - cng - lng - ethanol - propane - hydrogen required: - type - freeFlowSpeedTable type: object Location: description: 'Represents a geospatial location defined by latitude and longitude coordinates in WGS-84 format. Used to specify vehicle start and end positions, job locations, and other geographic points in tour planning.' properties: id: allOf: - $ref: '#/components/schemas/Id' description: 'Specifies the location ID. Avoid referencing any sensitive or personal information, such as names, addresses, or information about a delivery or service. If specified and custom matrix provided, there is no need to pass latitude and longitude.' lat: description: Specifies the latitude coordinate in WGS-84 degrees. example: 52.53088 format: double maximum: 90 minimum: -90 type: number lng: description: Specifies the longitude coordinate in WGS-84 degrees. example: 13.38471 format: double maximum: 180 minimum: -180 type: number type: object Fleet: description: "Represents the [collection of vehicles](https://docs.here.com/tour-planning/docs/problem#fleet) used for\ncompleting the planned tours. Each vehicle in the fleet can have specific attributes, such as:\n * Vehicle type (for example, truck, van, scooter)\n * Capacity (for example, volume, weight)\n * Operational costs\n * Time shifts (availability times)\n * Start and end locations\n * Special features (for example, refrigeration, hazmat compliance)\n * Routing profiles (for example, car, truck, bicycle)" properties: profiles: example: - name: normal_car type: car items: $ref: '#/components/schemas/Profile' maxItems: 5 minItems: 1 type: array traffic: default: automatic description: "Define how traffic is considered in route planning with the following [traffic modes](https://docs.here.com/tour-planning/docs/traffic-modes):\n * **liveOrHistorical**: Uses live or historical traffic data based on the optional `departureTime`\n property in a vehicle profile. For future times, it uses live data if within a 490 km radius; otherwise,\n it uses historical data. For past times, it uses historical data. If you do not set the `departureTime`\n value, the earliest shift start time is used instead.\n * **historicalOnly**: Uses free-flow speeds based on historical traffic data. Applicable if you\n want to avoid using live traffic data.\n * **automatic**: Functions like `liveOrHistorical` if all coordinates are within a 490 km radius;\n otherwise, it functions like `historicalOnly`. Applicable if you want to let the service\n automatically decide the best option.\n\nYou can also set the traffic mode to `disabled` in the fleet's `profile.traffic` settings." enum: - liveOrHistorical - historicalOnly - automatic example: liveOrHistorical type: string types: description: 'Represents different categories of vehicles used to optimize routes and deliveries. These types can vary based on factors like capacity (how much a vehicle can carry), dimensions (size of the vehicle), and specific features (for example, refrigeration for perishable goods). The synchronous endpoint supports up to 35 vehicle types, while the asynchronous endpoint supports up to 150 vehicle types.' items: $ref: '#/components/schemas/VehicleType' minItems: 1 type: array required: - types - profiles type: object VehicleReload: description: Specifies a place where vehicle can load or unload cargo. properties: duration: $ref: '#/components/schemas/Duration' location: $ref: '#/components/schemas/RoutingLocation' tag: $ref: '#/components/schemas/PlaceTag' times: $ref: '#/components/schemas/TimeWindows' required: - location - duration type: object Violations: description: '**ALPHA** Contains information about tour violations.' properties: timeWindows: $ref: '#/components/schemas/TimeWindowsViolations' type: object x-maturity: alpha ExperimentalFeatures: description: 'Lists the enabled [experimental features](https://docs.here.com/tour-planning/docs/experimental-features) that are still under development. These experimental features are provided for testing and feedback purposes, and their availability or functionality might change.' items: type: string minItems: 1 type: array Exclude: description: Defines properties which will be strictly excluded from route calculation. properties: areas: items: $ref: '#/components/schemas/AvoidArea' maxItems: 250 minItems: 1 type: array countries: description: A list of country codes in ISO 3166-1 alpha-3 format to exclude from tour planning. The routes can be found only if any valid route exists within 200km of the center of the locations' distribution circle. items: $ref: '#/components/schemas/CountryCode' type: array uniqueItems: true type: object VehiclePlace: description: 'Represents a depot: a place where a vehicle starts or ends.' properties: location: $ref: '#/components/schemas/RoutingLocation' tag: $ref: '#/components/schemas/PlaceTag' time: $ref: '#/components/schemas/DateAndTime' timeOffset: description: 'The property `timeOffset` specifies an offset in seconds from given `time` property. For start place, it defines a maximum time offset for departure time optimization (but it is not more than maximum shift duration). So far, it has no effect for vehicle''s end place (reserved for a future usage).' example: 1800 format: int64 maximum: 86400 minimum: 0 type: integer required: - time type: object VehicleMaxStopsCountLimit: description: Hard limit on the maximum number of stops in a shift. properties: value: description: The maximum number of stops allowed in a vehicle shift. example: 1 minimum: 1 type: integer required: - value type: object Compartment: description: '**ALPHA** a definition of a compartment representing part of the vehicle load' properties: capacity: $ref: '#/components/schemas/Unit' description: Capacity of the compartment name: allOf: - $ref: '#/components/schemas/Id' description: 'Name of the compartment, used for referencing the compartment, each compartment in the vehicle must be unique' example: compartmentA required: - name - capacity type: object x-maturity: alpha Pudo: description: '**BETA** Represents a specific location called [PUDO (or pick-up and drop-off point)](https://docs.here.com/tour-planning/docs/group-jobs#job-groups-with-pudos) where goods or passengers are picked up or dropped off as part of a tour. PUDOs help in streamlining the loading and unloading process to minimize travel distances and reduce the overall travel time.' properties: assignAt: description: 'Indicates whether the PUDO must be the first or last activity in the group. This helps in organizing the sequence of tasks efficiently.' enum: - first - last example: first type: string id: description: 'The [PUDO](https://docs.here.com/tour-planning/docs/group-jobs#job-groups-with-pudos) ID. This ID must be unique across the entire problem, including job IDs.' example: pudo1 type: string places: description: 'List of locations that are available as pick-up and drop-off PUDOs. Assigning multiple locations as PUDOs allows for efficient task completion based on availability and convenience.' items: $ref: '#/components/schemas/PudoPlace' maxItems: 3 minItems: 1 type: array required: - id - assignAt - places type: object x-maturity: beta OptimizeTaskPosition: description: An objective to control position of job task activities in the tour. When specified, the task position is considered as a soft constraint and the solver tries to minimize amount of its violations. properties: isConstrained: default: false description: If the property is set to true, then order is enforced as hard constraint. example: false type: boolean type: enum: - optimizeTaskPosition example: optimizeTaskPosition type: string required: - type type: object RouteDetailsConfiguration: description: 'Include [route details](https://docs.here.com/tour-planning/docs/polylines) between each stop in the solution, in the [flexible polyline](https://github.com/heremaps/flexible-polyline/blob/master/README.md) format. For each stop (X), the polyline represents the route between that stop and the previous one (X-1).' example: - polyline items: type: string x-extensible-enum: - polyline minItems: 1 type: array MaxDurationStrategy: description: 'Sets the cluster''s total duration to the longest job duration. This strategy is useful when multiple tasks for the same customer don''t significantly increase overall time.' example: type: maxDurationStrategy properties: type: enum: - maxDurationStrategy example: maxDurationStrategy type: string required: - type type: object MatrixId: description: '**ALPHA** Unique identifier (UUID) of the uploaded matrix' example: 87aec2ce-b697-11e8-96f8-529269fb1459 maxLength: 36 minLength: 36 pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$ type: string x-maturity: alpha AvoidSegment: description: 'A segment identifier that routes will avoid going through. Each entry has the following structure: {segmentId}(#{direction})? The individual parts are: * segmentId: The identifier of the referenced topology segment, example: here:cm:segment:207551710 * direction (optional): Either ''`*`'' for bidirectional (default), ''+'' for positive direction, or ''-'' for negative direction. Example of a parameter value excluding two segments: [\"here:cm:segment:207551710#+\", \"here:cm:segment:76771992#*\"] **Note**: Maximum amount of penalized segments in one request should not be greater than 250. A \"penalized segment\" refers to a segment that have a restrictions on maximum baseSpeed with maxSpeedOnSegment or avoided with avoid[segments]' example: here:cm:segment:207551710 pattern: ^[A-Za-z0-9-]+:[A-Za-z0-9-]+:segment:[0-9]+(#\+|#\*|#\-)?$ type: string VehicleJobCost: description: '**ALPHA** Per-job cost function on vehicle costs.' properties: overrides: description: Optional overrides for specific jobs. If a job ID matches, the override cost is used directly. items: $ref: '#/components/schemas/JobCostOverride' minItems: 1 type: array rate: $ref: '#/components/schemas/JobCostRate' description: Rate multiplied by job's costFactor. Cost per job = costFactor × rate. required: - rate type: object x-maturity: alpha Statistic: description: 'Provides [metrics](https://docs.here.com/tour-planning/docs/solution#statistic) about the performance and efficiency of vehicles across all tours. These metrics include a range of data, offering insights into the costs, distances, and durations that are associated with the optimized route.' properties: co2Emission: description: 'The estimated CO2 emissions for this section of the route that are calculated based on the fuel type and consumption. The unit of measurement is kilograms.' example: 5.761 format: double type: number consumption: description: 'The estimated [net fuel consumption](https://docs.here.com/tour-planning/docs/co-emissions) that is measured in distinct units for different types of fuel. For diesel, petrol, and Liquefied Petroleum Gas (LPG) vehicles, fuel consumption is expressed in liters. In contrast, Compressed Natural Gas (CNG) vehicles use kilograms to measure their fuel consumption.' example: 2.1821 format: double type: number cost: description: Represents the total cost of all tours within a solution, calculated in abstract units. example: 1024 format: double minimum: 0 type: number costs: allOf: - $ref: '#/components/schemas/CostStatistics' description: Breakdown of cost into individual components. Only present fields contribute to the total cost. x-maturity: alpha distance: description: Indicates the cumulative distance, measured in meters, that all vehicles have traveled across all tours. example: 32000 format: int64 minimum: 0 type: integer duration: $ref: '#/components/schemas/Duration' intraStopDistance: description: 'The total distance (in meters) between activities inside all the Stops plus the way back to the stop locations.' example: 1024 format: int64 minimum: 0 type: integer times: $ref: '#/components/schemas/Timing' violations: $ref: '#/components/schemas/Violations' required: - cost - distance - duration - times type: object VehicleShiftMixingRestrictions: description: Enables the prevention of mixing conflicting jobs within a single vehicle. properties: level: enum: - tour - subTour example: tour type: string restrictions: description: Represents a set of conflicting job categories. items: $ref: '#/components/schemas/MixingRestrictionSet' maxItems: 100 minItems: 1 type: array required: - level - restrictions type: object VehicleCharging: description: '**ALPHA** Specifies vehicle charging properties.' example: evProfileId: '10' maxCharge: 80 minCharge: 20 setupDuration: 300 properties: evProfileId: allOf: - $ref: '#/components/schemas/Id' description: Identifier of the electric vehicle profile from HERE EV Profiles Service that contains information about the vehicle's battery capacity, consumption rates, and charging capabilities. initialCharges: items: $ref: '#/components/schemas/VehicleInitialCharge' minItems: 1 type: array uniqueItems: true maxCharge: description: Target battery charge level (in percentage) at which charging should stop. example: 80 format: int32 maximum: 100 minimum: 0 type: integer maxDistance: description: Maximum traveled distance before charging station has to be visited (in meters). example: 10000 format: int32 maximum: 10000000 minimum: 1 type: integer minCharge: description: Minimum battery charge level (in percentage) below which the vehicle must visit a charging station. example: 20 format: int32 maximum: 100 minimum: 0 type: integer setupDuration: $ref: '#/components/schemas/Duration' usePublicStations: default: true description: Whether to use public charging stations for this vehicle type. Default is true. type: boolean type: object x-maturity: alpha TruckOptions: allOf: - $ref: '#/components/schemas/VehicleOptions' description: Specifies truck profile options. Supported only if the locations' distribution radius is less than 490 km. If not added, only generic truck restrictions are applied and the fastest speed category is considered. VehicleStopsLimit: description: 'Limits on the amount of stops a vehicle of that type can perform in a shift. A stop is only counted if at least one pickup or delivery is performed as part of that stop. An initial/final stop at the depot is never counted to the number of stops.' example: maxCount: value: 13 minCount: value: 5 properties: maxCount: $ref: '#/components/schemas/VehicleMaxStopsCountLimit' minCount: $ref: '#/components/schemas/VehicleMinStopsCountLimit' type: object EagerDeliveryOptions: description: "**ALPHA** Specifies if the eager delivery feature is active. Here 'eager' means that the delivery driver will\ntry to perform jobs 'on the way there' and not 'on the way back'. As an example, consider the street network\n\n```markdown\n D\n |\n A----B----C\n```\nand the driver starting at A. If the eager delivery feature is enabled, the driver will prefer to serve the jobs\nin the order ABCD even if ACBD might have slightly better cost." properties: additionalWeightAtFirstEdge: description: Scaling factor that decreases monotonically as the tour goes on. example: 0.5 format: double type: number enabled: description: Whether the eager delivery feature is enabled. example: true type: boolean improvementThreshold: description: How big the improvement must be w.r.t. 'eagerness' for us to consider allowing a degradation of the cost. example: 0.1 format: double type: number tieThreshold: description: How much we are willing to give w.r.t. cost to get more 'eager' tours. example: 0.1 format: double type: number required: - enabled type: object x-maturity: alpha RouteViolation: description: 'Defines route violation. Violation happens only if no feasible route without violations between i and j was found - `all`: Includes all violations, such as traffic violations, car restrictions, etc. - `traffic`: **ALPHA** Deprecated, please use violationMapping instead. Includes only traffic violations, such as closed roads, bridges, etc. This option is only available for the `car` or `truck` profile. - `category1`: Includes only category 1 violations, see `violationMapping` property for details. - `category2`: Includes only category 2 violations, see `violationMapping` property for details. - `allExceptCategory1`: Ignores all violations except category 1 violations. - `allExceptCategory2`: Ignores all violations except category 2 violations. - `allExceptCategory1AndCategory2`: Ignores all violations except category 1 and category 2 violations.' enum: - all - traffic - category1 - category2 - allExceptCategory1 - allExceptCategory2 - allExceptCategory1AndCategory2 example: all type: string PlaceTag: description: 'An optional free-text field submitted as part of the problem request, providing additional information related to the task''s place for easier identification or categorization. A user-defined tag associated with a given place that is propagated back within the solution. Use it to distinguish between different job places. Do not include any personal information within the `PlaceTag`. For example, avoid using specific names of individuals associated with the place.' example: some_tag maxLength: 128 minLength: 1 pattern: ^[a-zA-Z0-9_-]+$ type: string VehicleRestTime: description: '**BETA** Defines rest times for a vehicle shift for driving, working and duty. Either a rest time or a break can be specified.' properties: driving: $ref: '#/components/schemas/VehicleDrivingRestTime' dutyRule: $ref: '#/components/schemas/VehicleDutyRestTime' working: $ref: '#/components/schemas/VehicleWorkingRestTime' type: object x-maturity: beta TieBreakObj: description: '**ALPHA** A single objective as a part of the TieBreak objective. Note that the objective must not be a composite objective itself. It is, e.g., not possible to put another TieBreak objective here.' properties: improvementThreshold: description: 'If the decision was delegated to this objective by a higher-level objective, two solutions must differ by at least this threshold in order to select one over the other.' example: 0.1 format: double maximum: 1 minimum: 0 type: number objective: $ref: '#/components/schemas/AsTieBreakObjective' tieThreshold: description: If two solutions are within the given threshold for this objective, the decision will be delegated to the next objective in the list. example: 0.05 format: double maximum: 1 minimum: 0 type: number required: - objective type: object x-maturity: alpha HouseKeysStrategy: description: Specifies the duration strategy for house keys. discriminator: mapping: boundedSum: '#/components/schemas/HouseKeysBoundedSumStrategy' fixedDuration: '#/components/schemas/HouseKeysFixedDurationStrategy' maxDuration: '#/components/schemas/HouseKeysMaxDurationStrategy' propertyName: type oneOf: - $ref: '#/components/schemas/HouseKeysMaxDurationStrategy' - $ref: '#/components/schemas/HouseKeysFixedDurationStrategy' - $ref: '#/components/schemas/HouseKeysBoundedSumStrategy' x-maturity: alpha Objective: discriminator: mapping: minimizeCost: '#/components/schemas/MinimizeCost' minimizeDistance: '#/components/schemas/MinimizeDistance' minimizeDuration: '#/components/schemas/MinimizeDuration' minimizeUnassigned: '#/components/schemas/MinimizeUnassigned' optimizeTaskOrder: '#/components/schemas/OptimizeTaskOrder' optimizeTaskPosition: '#/components/schemas/OptimizeTaskPosition' optimizeTourCount: '#/components/schemas/OptimizeTourCount' propertyName: type oneOf: - $ref: '#/components/schemas/MinimizeUnassigned' - $ref: '#/components/schemas/MinimizeCost' - $ref: '#/components/schemas/OptimizeTourCount' - $ref: '#/components/schemas/OptimizeTaskOrder' - $ref: '#/components/schemas/MinimizeDistance' - $ref: '#/components/schemas/MinimizeDuration' - $ref: '#/components/schemas/OptimizeTaskPosition' MaximizeTerritoryJobs: description: '**ALPHA** An objective to achieve desired jobs distribution between vehicles considering the territories in which these vehicles operate.' properties: type: enum: - maximizeTerritoryJobs example: maximizeTerritoryJobs type: string required: - type type: object x-maturity: alpha IgnoreRouteViolations: description: Defines vehicle routing violations (like closed road, no-through zone) that should be ignored. items: $ref: '#/components/schemas/RouteViolation' maxItems: 2 minItems: 1 type: array uniqueItems: true VehicleDutyRestTime: description: '**ALPHA** Defines duty rest time' discriminator: mapping: fixedDuration: '#/components/schemas/VehicleFixedDutyRestTime' propertyName: type oneOf: - $ref: '#/components/schemas/VehicleFixedDutyRestTime' x-maturity: alpha JobPositionInTour: description: 'Specifies the position of the job task in the tour. Use the `position` property to control the serving order of tasks within a tour. Job tasks with a `position` property are scheduled earlier in the route than job tasks without one, except for tasks with `position` set to `last`, which are always assigned last. The following position types are supported: - `first`: Schedules the task immediately after departure, before all other tasks. - `last`: Schedules the task at the end of the tour, after all other tasks. - `any`: Schedules the task anywhere in the tour between `first` and `last` tasks. - `ordered`: Schedules the task after `first` and before `last` tasks, according to a numeric `value`, where lower values are served earlier. **Note**: The `position` property does not affect whether a job is assigned. To influence assignment priority, use the `priority` property. For more information, see [Control job task position](https://docs.here.com/tour-planning/docs/job-task-order).' discriminator: mapping: any: '#/components/schemas/JobPositionAny' first: '#/components/schemas/JobPositionFirst' last: '#/components/schemas/JobPositionLast' ordered: '#/components/schemas/JobPositionOrdered' propertyName: type oneOf: - $ref: '#/components/schemas/JobPositionFirst' - $ref: '#/components/schemas/JobPositionLast' - $ref: '#/components/schemas/JobPositionAny' - $ref: '#/components/schemas/JobPositionOrdered' JobTasks: description: 'Tasks refer to specific actions that need to be performed as part of a job, such as pickups or deliveries at designated locations. Each job can consist of up to three pickup tasks and three delivery tasks. The order of execution inside each group can be any. At least one task must be specified as part of a job. **Note**: All pickups are done before any other delivery.' example: deliveries: - demand: - 10 places: - duration: 300 location: lat: 52.54016 lng: 13.40241 times: - - '2020-07-04T14:00:00Z' - '2020-07-04T16:00:00Z' pickups: - demand: - 10 places: - duration: 180 location: lat: 52.53088 lng: 13.38471 times: - - '2020-07-04T10:00:00Z' - '2020-07-04T12:00:00Z' properties: deliveries: items: $ref: '#/components/schemas/JobTask' maxItems: 3 minItems: 1 type: array pickups: items: $ref: '#/components/schemas/JobTask' maxItems: 3 minItems: 1 type: array type: object ShippedHazardousGoods: description: "List of hazardous materials in the vehicle.\n * explosive: Explosive material\n * gas: Gas\n * flammable: Flammable material\n * combustible: Combustible material\n * organic: Organic material\n * poison: Poison\n * radioactive: Radioactive material\n * corrosive: Corrosive material\n * poisonousInhalation: Materials that are poisonous upon inhalation\n * harmfulToWater: Materials that are harmful to water\n * other: Other types of hazardous materials" enum: - explosive - gas - flammable - combustible - organic - poison - radioactive - corrosive - poisonousInhalation - harmfulToWater - other type: string VehicleCosts: description: Defines different vehicle costs per unit. properties: distance: description: A cost per meter. It is optional with a default value of zero. example: 0.0001 format: double maximum: 100000 minimum: 0 type: number excessCosts: allOf: - $ref: '#/components/schemas/ExcessCosts' x-maturity: beta fixed: description: A fixed cost to start using vehicle of this type. It is optional with a default value of zero example: 22 format: double maximum: 100000 minimum: 0 type: number perJob: $ref: '#/components/schemas/VehicleJobCost' perWaitingTime: description: A cost per second for waiting times. If not set, a regular time cost is used. example: 0.01 format: double maximum: 100000 minimum: 0 type: number time: description: 'A cost per second. It is optional with a default value of zero. Both time and distance costs cannot be specified as 0. If time and distance costs are not specified at all, then a small time cost 0.00000000001 will be used instead.' example: 0.0048 format: double maximum: 100000 minimum: 0 type: number type: object Timing: description: 'Contains detailed time consumption information for various activity types during a tour. All durations are in seconds and represent the total time spent on different activities. Includes driving time between locations, serving time for job activities, waiting time to meet time window constraints, stopping time, break time, and intra-stop time.' example: break: 1200 driving: 3600 serving: 600 stopping: 100 waiting: 180 properties: break: $ref: '#/components/schemas/Duration' charging: $ref: '#/components/schemas/Duration' driving: $ref: '#/components/schemas/Duration' intraStop: $ref: '#/components/schemas/Duration' serving: $ref: '#/components/schemas/Duration' stopping: $ref: '#/components/schemas/Duration' waiting: $ref: '#/components/schemas/Duration' required: - driving - serving - waiting - break - stopping type: object ServeInClusters: description: '**ALPHA** An objective to serve jobs in clusters' properties: maxClusterRadius: default: 800 description: 'Specifies a radius in meters in which job locations are clustered. Jobs in the same cluster are served consecutively before moving on the next cluster. Suitable values for the parameter depend on the job distribution and need to be tuned until satisfactory results are achieved.' example: 300 format: int64 maximum: 100000 minimum: 10 type: integer type: enum: - serveInClusters example: serveInClusters type: string required: - type type: object x-maturity: alpha ViolationMappingItemAvoidAreasAndSegments: description: 'Allows the mapping of user specified avoidance of areas or individual segments. This type of mapping is supported for transport modes `car` and `truck`.' properties: category: $ref: '#/components/schemas/ViolationMappingCategory' type: enum: - avoidAreasAndSegments example: avoidAreasAndSegments type: string required: - category - type type: object VehicleShift: description: Specifies how vehicle should operate in one work shift. example: breaks: - duration: 1800 times: - - '2020-07-04T11:00:00Z' - '2020-07-04T13:00:00Z' - duration: 900 times: - - '2020-07-04T15:00:00Z' - '2020-07-04T16:00:00Z' end: location: lat: 52.5256 lng: 13.4542 time: '2020-07-04T18:00:00Z' start: location: lat: 52.5256 lng: 13.4542 time: '2020-07-04T09:00:00Z' properties: breaks: items: $ref: '#/components/schemas/VehicleBreak' maxItems: 5 minItems: 1 type: array end: $ref: '#/components/schemas/VehiclePlace' mixingRestrictions: $ref: '#/components/schemas/VehicleShiftMixingRestrictions' reloads: items: $ref: '#/components/schemas/VehicleReload' maxItems: 5 minItems: 1 type: array restTimes: $ref: '#/components/schemas/VehicleRestTime' start: $ref: '#/components/schemas/VehiclePlace' stopBaseDuration: description: 'A constant duration of time, in seconds, added at stops. This can be used to model, for example, vehicle parking time, vehicle preparation for loading/unloading or some facility entrance procedures.' properties: type: enum: - oncePerStop example: oncePerStop type: string value: default: 0 description: The duration, in seconds, added per stop example: 10 format: double maximum: 36000 minimum: 0 type: number required: - type - value type: object stopConfig: $ref: '#/components/schemas/StopConfig' stopConfiguration: $ref: '#/components/schemas/StopConfiguration' required: - start type: object AvoidRoutes: description: Avoid routes that violate these properties. properties: areas: items: $ref: '#/components/schemas/AvoidArea' maxItems: 250 minItems: 1 type: array features: items: $ref: '#/components/schemas/AvoidFeatures' type: array uniqueItems: true segments: items: $ref: '#/components/schemas/AvoidSegment' maxItems: 250 minItems: 1 type: array uniqueItems: true truckRoadTypes: items: $ref: '#/components/schemas/AvoidTruckRoadType' minItems: 1 type: array uniqueItems: true zoneCategories: properties: categories: items: $ref: '#/components/schemas/AvoidZoneCategory' minItems: 1 type: array uniqueItems: true exceptZoneIds: items: $ref: '#/components/schemas/AvoidZone' minItems: 1 type: array uniqueItems: true required: - categories type: object zoneIdentifiers: items: $ref: '#/components/schemas/AvoidZone' minItems: 1 type: array uniqueItems: true type: object ViolationMappingItemTraffic: description: 'Allows the mapping of traffic related blockages. Mapping of traffic blockages is supported for transport modes `car` and `truck`.' properties: bridge: allOf: - $ref: '#/components/schemas/ViolationMappingOptionalField' default: ignore description: 'Specifies whether the violation is considered only if it occurs on a bridge, only if it does not occur on a bridge, or in both cases.' category: $ref: '#/components/schemas/ViolationMappingCategory' type: enum: - traffic example: traffic type: string required: - category - type type: object ViolationMappingItemRestriction: description: 'Allows the mapping of violations of selected restrictions. Mapping of violated restrictions is supported for transport mode `truck`. For the type of `restriction`, at least one of the concrete restrictions, e.g., `grossWeight`, `currentWeight` or `height`, must be specified with value `include` or `ignore`. For example: - `{ "category": "category1", "type": "restriction", "grossWeight": "include" }` - `{ "category": "category1", "type": "restriction", "height": "ignore" }`' properties: bridge: allOf: - $ref: '#/components/schemas/ViolationMappingOptionalField' default: ignore description: 'Specifies whether the violation is considered only if it occurs on a bridge, only if it does not occur on a bridge, or in both cases.' category: $ref: '#/components/schemas/ViolationMappingCategory' currentWeight: allOf: - $ref: '#/components/schemas/ViolationMappingOptionalField' default: exclude description: 'Indicates whether current weight violation is included or excluded for this category. **NOTE:** A weight restriction can be of type `unknown`, meaning it may apply to either gross or current weight. If both the vehicle’s current_weight and gross_weight violate an `unknown` weight restriction, and the user requests a violation mapping for only one of them (e.g., using gross_weight:include or current_weight:include), the service will assign the `unknown` weight restriction to the included weight type. Similarly, if either the vehicle’s current_weight or gross_weight violates an `unknown` weight restriction, the service will assign the `unknown` weight restriction to the specific weight type that exceeds the allowed limit.For example: * gross_weight=15000, current_weight=10000 * weight_restriction_type=Unknown with value 12000 * Since gross_weight (15,000) exceeds the restriction (12,000), the `unknown` weight restriction will be mapped to gross_weight rather than current_weight. User in this case will get an error code 3. * Please note that a restriction of type `unknown` may change To `gross` or `current` when data becomes available in future. Similarly a restriction of type `gross` or `current` may also change to a different type if actual regulation changes.' grossWeight: allOf: - $ref: '#/components/schemas/ViolationMappingOptionalField' default: exclude description: 'Indicates whether gross weight violation is included or excluded for this category. **NOTE:** A weight restriction can be of type `unknown`, meaning it may apply to either gross or current weight. If both the vehicle’s current_weight and gross_weight violate an `unknown` weight restriction, and the user requests a violation mapping for only one of them (e.g., using gross_weight:include or current_weight:include), the service will assign the `unknown` weight restriction to the included weight type. Similarly, if either the vehicle’s current_weight or gross_weight violates an `unknown` weight restriction, the service will assign the `unknown` weight restriction to the specific weight type that exceeds the allowed limit.For example: * gross_weight=15000, current_weight=10000 * weight_restriction_type=Unknown with value 12000 * Since gross_weight (15,000) exceeds the restriction (12,000), the `unknown` weight restriction will be mapped to gross_weight rather than current_weight. User in this case will get an error code 3. * Please note that a restriction of type `unknown` may change To `gross` or `current` when data becomes available in future. Similarly a restriction of type `gross` or `current` may also change to a different type if actual regulation changes.' height: allOf: - $ref: '#/components/schemas/ViolationMappingOptionalField' default: exclude description: 'Indicates whether height violation is included or excluded from this category.' timeDependent: allOf: - $ref: '#/components/schemas/ViolationMappingOptionalField' default: ignore description: 'Specifies whether the time dependent violation of restrictions is included, excluded or ignored for this category.' type: enum: - restriction example: restriction type: string required: - category - type type: object ViolationMappingCategory: description: 'The category number assigned to this violation mapping item. Two categories are supported, with values 1 and 2 available to categorize the mapping items.' enum: - category1 - category2 example: category1 type: string CountryCode: description: ISO-3166-1 alpha-3 country code. example: DEU maxLength: 3 minLength: 3 type: string UnassignedJobDetail: description: '**ALPHA** Details about job unassignment such as vehicle id, shift index. This can help to analyze how to modify the problem definition to decrease amount of unassigned jobs.' properties: shiftIndex: $ref: '#/components/schemas/ShiftIndex' vehicleIds: items: $ref: '#/components/schemas/Id' minItems: 1 type: array required: - vehicleIds - shiftIndex type: object x-maturity: alpha StopConfig: deprecated: true description: '**ALPHA** Configures how stops are created. Specifies how multiple jobs located close to each other can be grouped into a single stop. Please consult the developer guide for more information before using this feature. To enable it, add `clusterNearby` flag to `experimentalFeatures` configuration in the problem.' discriminator: mapping: dbscan: '#/components/schemas/DbscanStopConfig' propertyName: type oneOf: - $ref: '#/components/schemas/DbscanStopConfig' x-maturity: alpha AsTieBreakObjective: discriminator: mapping: balanceActivities: '#/components/schemas/BalanceActivities' balanceDistance: '#/components/schemas/BalanceDistance' balanceDuration: '#/components/schemas/BalanceDuration' balanceMaxLoad: '#/components/schemas/BalanceMaxLoad' maximizePriorityJobs: '#/components/schemas/MaximizePriorityJobs' maximizeTerritoryJobs: '#/components/schemas/MaximizeTerritoryJobs' minimizeCost: '#/components/schemas/MinimizeCost' minimizeDistance: '#/components/schemas/MinimizeDistance' minimizeDuration: '#/components/schemas/MinimizeDuration' minimizeSoftTimeWindowViolations: '#/components/schemas/MinimizeSoftTimeWindowViolations' minimizeTourOverlap: '#/components/schemas/MinimizeTourOverlap' optimizeTaskPosition: '#/components/schemas/OptimizeTaskPosition' serveInClusters: '#/components/schemas/ServeInClusters' propertyName: type oneOf: - $ref: '#/components/schemas/MinimizeCost' - $ref: '#/components/schemas/MinimizeDistance' - $ref: '#/components/schemas/MinimizeDuration' - $ref: '#/components/schemas/MinimizeTourOverlap' - $ref: '#/components/schemas/BalanceMaxLoad' - $ref: '#/components/schemas/BalanceActivities' - $ref: '#/components/schemas/BalanceDistance' - $ref: '#/components/schemas/BalanceDuration' - $ref: '#/components/schemas/ServeInClusters' - $ref: '#/components/schemas/MaximizePriorityJobs' - $ref: '#/components/schemas/OptimizeTaskPosition' - $ref: '#/components/schemas/MinimizeSoftTimeWindowViolations' - $ref: '#/components/schemas/MaximizeTerritoryJobs' x-maturity: alpha ServiceTimeStrategy: description: 'Controls how the duration or service time of job clusters is determined. Selecting a service strategy type is useful in scenarios where multiple jobs are served at the same location or are located nearby. It has the following types: * `maxDurationStrategy`: The total duration of the job cluster equals the duration of the job with the longest duration. * `fixedDurationStrategy`: The total duration of the job cluster is fixed, as defined in the strategy object. * `boundedSumStrategy`: The total duration of a job cluster equals the sum of the durations of the jobs, bounded by a given maximum.' discriminator: mapping: boundedSumStrategy: '#/components/schemas/BoundedSumStrategy' fixedDurationStrategy: '#/components/schemas/FixedDurationStrategy' maxDurationStrategy: '#/components/schemas/MaxDurationStrategy' propertyName: type oneOf: - $ref: '#/components/schemas/FixedDurationStrategy' - $ref: '#/components/schemas/MaxDurationStrategy' - $ref: '#/components/schemas/BoundedSumStrategy' JobPositionLast: description: 'Puts the job task at the end of the tour. If an assignment is labeled with the `last` position, the API prioritizes it as the final task to be handled after all other assignments, regardless of their position values.' properties: type: enum: - last example: last type: string required: - type type: object MinimizeCost: description: Minimizes the total solution cost properties: eagerDelivery: $ref: '#/components/schemas/EagerDeliveryOptions' type: enum: - minimizeCost example: minimizeCost type: string required: - type type: object TooManyRequestsResponse: properties: error: description: Provides an error message based on the status code. example: Too Many Requests type: string error_description: description: Provides detailed information about an authentication or authorization error. example: Rate limit for this service has been reached type: string required: - error - error_description type: object BicycleProfile: description: 'Routing calculations for bicycles. The `departureTime` property allows to specify a custom date-time for which `traffic optimization` in routing calculations shall be performed. See `fleet.traffic` for details.' properties: avoid: $ref: '#/components/schemas/AvoidRoutes' departureTime: $ref: '#/components/schemas/DateAndTime' exclude: $ref: '#/components/schemas/Exclude' ignoreRouteViolations: $ref: '#/components/schemas/IgnoreRouteViolations' matrix: $ref: '#/components/schemas/Matrix' matrixId: $ref: '#/components/schemas/MatrixId' name: $ref: '#/components/schemas/ProfileName' traffic: $ref: '#/components/schemas/Traffic' type: enum: - bicycle example: bicycle type: string violationMapping: $ref: '#/components/schemas/ViolationMapping' required: - name - type type: object PedestrianProfile: description: 'Routing calculations for pedestrians. The `departureTime` property allows to specify a custom date-time for which `traffic optimization` in routing calculations shall be performed. See `fleet.traffic` for details.' properties: avoid: $ref: '#/components/schemas/AvoidRoutes' departureTime: $ref: '#/components/schemas/DateAndTime' exclude: $ref: '#/components/schemas/Exclude' ignoreRouteViolations: $ref: '#/components/schemas/IgnoreRouteViolations' matrix: $ref: '#/components/schemas/Matrix' matrixId: $ref: '#/components/schemas/MatrixId' name: $ref: '#/components/schemas/ProfileName' options: $ref: '#/components/schemas/PedestrianOptions' traffic: $ref: '#/components/schemas/Traffic' type: enum: - pedestrian example: pedestrian type: string violationMapping: $ref: '#/components/schemas/ViolationMapping' required: - name - type type: object VehicleCategory: description: "Specifies the category of vehicle. If not specified, `undefined` value is used.\n * `undefined`: The vehicle category is undefined and no special considerations are taken into account. Routing will proceed as normal.\n * `lightTruck`: The vehicle is a truck light enough to be classified more as a car than as a truck, i.e., this exempts it from many legal restrictions for normal trucks.\n Restrictions related to the physical dimensions of the truck, or its cargo, however, still apply." enum: - undefined - lightTruck type: string JobCostOverride: description: '**ALPHA** Per-job cost override for a specific job ID. When matched, the override cost is used directly.' properties: cost: description: The flat cost to charge for this job (not multiplied by costFactor). example: 5 format: double maximum: 100000 minimum: 0 type: number jobId: $ref: '#/components/schemas/Id' description: The job ID to match. required: - jobId - cost type: object x-maturity: alpha ExcessCostsField: description: Specifies limits on a solution metric and penalties to be paid in case those limits are violated. properties: fixedCost: description: A fixed cost to be paid if the limit is exceeded. example: 2030 format: double minimum: 0 type: number limit: description: A limit that the solution should not exceed. If it is exceeded, a penalty is added to the solution cost. example: 200 format: double minimum: 0 type: number stepCost: description: The cost per step of excess. example: 5 format: double minimum: 0 type: number stepSize: description: Excess is measured in steps. E.g., if the step size is 12 and the excess is 14, we would incur ceil(14/2) = 2 units of penalty. example: 20 format: double minimum: 0 type: number required: - limit - fixedCost - stepSize - stepCost type: object x-maturity: beta AvoidZoneCategory: description: Specify avoidance of entire category of routing zones, with the provision to add individual exceptions. enum: - vignette - congestionPricing - environmental example: vignette type: string MatrixOriginId: description: Specifies the origin location used in custom matrix. properties: id: allOf: - $ref: '#/components/schemas/Id' description: 'Specifies id of the origin. Avoid referencing any sensitive or personal information, such as names, addresses, information about a delivery or service.' type: enum: - id example: id type: string required: - id - type type: object Parking: description: '**ALPHA** Represents a parking space or car park with id that vehicles can use during their tours.' properties: id: allOf: - $ref: '#/components/schemas/Id' description: Represents the unique ID of a car park or parking space. example: parking1 places: description: List of places that are available as parking places. items: $ref: '#/components/schemas/ParkingPlace' maxItems: 10 minItems: 1 type: array required: - id - places type: object x-maturity: alpha Territory: description: Conceptually represents a geographical region that can be used to restrict the geographical area in which vehicles operate. If defined, vehicles will only/primarily serve jobs which have a matching territory id defined, see JobPlace.territoryIds. properties: id: allOf: - $ref: '#/components/schemas/Id' description: A territory identifier. It can be used to express in which territory a job is located, see JobPlace.territoryIds example: territory1 priority: default: 1 description: Can be used to prioritize between different territories of the same vehicle type. Lower value means higher priority. Jobs belonging to high priority territories will be prioritized over jobs belonging to territories with lower priority. Can also be used to prioritize between the same territories of different vehicle types, i.e. different vehicle types can serve jobs belonging to the same territory, but with different priority. example: 1 maximum: 5 minimum: 1 type: integer required: - id type: object Stop: description: 'Represents a [specific geographical location](https://docs.here.com/tour-planning/docs/solution#stop) where a vehicle is scheduled to perform one or more activities related to jobs, such as `pickups`, `deliveries`, or `breaks`.' properties: activities: description: 'Provides a list of activities like `pickup`, `delivery`, `arrival`, `break`, and so on, scheduled to occur at the stop during the tour.' items: $ref: '#/components/schemas/Activity' type: array consumption: description: '**ALPHA** Energy consumption since departure from start (in kWh or similar unit). Only present when consumption-based recharging is enabled.' example: 2.1821 format: double type: number x-maturity: alpha distance: description: 'The total distance (in meters) that a vehicle travelled from the depot (the start location of the tour) up to the stop location.' example: 1024 format: int64 minimum: 0 type: integer intraStopDistance: description: 'The total distance (in meters) between activities in this Stop plus the way back to the stop location If the stop location is equal to all activity locations in the stop it is 0.' example: 1024 format: int64 minimum: 0 type: integer load: $ref: '#/components/schemas/Unit' loadPerCompartment: items: properties: load: $ref: '#/components/schemas/Unit' name: $ref: '#/components/schemas/Id' description: Id of the compartment required: - name - load type: object type: array x-maturity: alpha location: $ref: '#/components/schemas/Location' routeDetails: $ref: '#/components/schemas/RouteDetails' time: $ref: '#/components/schemas/Schedule' required: - time - load - activities type: object DateAndTime: description: 'Represents a date-time value formatted according to RFC3339. Used to specify precise timestamps for job time windows, vehicle shift start and end times, break times, and other time-based constraints. Times in the solution are always returned in UTC.' example: '2020-07-04T00:00:00Z' format: date-time maxLength: 32 minLength: 1 type: string Id: description: 'A unique identifier of an entity. Avoid referencing any confidential or personal information as part of the `Id`.' example: 7f3423c2-784a-4983-b472-e14107d5a54a maxLength: 128 minLength: 1 pattern: ^[a-zA-Z0-9_-]+$ type: string EncodedPolygonArea: description: 'A polygon defined as a [Flexible Polyline](https://github.com/heremaps/flexible-polyline) encoded string. The polygon is automatically closed, so repeating the first vertex is not required.' properties: outer: description: '[Flexible Polyline](https://github.com/heremaps/flexible-polyline) that defines the outline of the polygon. Notes: * Support only 2D polyline (without `elevation` specified). * Minimum count of vertices in polygon is 3. * Maximum count of vertices in polygon is 100.' example: B F oz5xJ 67i1B 1B 7P zI ha xL 7Y type: string type: enum: - encodedPolygon example: encodedPolygon type: string required: - outer - type type: object VehicleOptions: properties: axleCount: description: 'Specifies the total number of axles the vehicle has, i.e., axles on the base vehicle and any attached trailers.' example: 3 format: int32 maximum: 255 minimum: 2 type: integer category: $ref: '#/components/schemas/VehicleCategory' grossWeight: description: Total vehicle weight, including trailers and shipped goods, in kilograms. example: 1000 minimum: 0 type: integer height: description: Vehicle height, in centimeters. example: 3000 maximum: 5000 minimum: 0 type: integer length: description: Vehicle length, in centimeters. example: 6000 maximum: 30000 minimum: 0 type: integer shippedHazardousGoods: items: $ref: '#/components/schemas/ShippedHazardousGoods' type: array speedCap: $ref: '#/components/schemas/SpeedCap' trailerCount: description: The number of trailers attached to the vehicle. example: 0 format: int32 maximum: 255 minimum: 0 type: integer tunnelCategory: $ref: '#/components/schemas/TunnelCategory' weightPerAxle: description: 'Vehicle weight per axle, in kilograms. **Note:** `weightPerAxle` and `weightPerAxleGroup` are incompatible.' example: 500 minimum: 0 type: integer weightPerAxleGroup: $ref: '#/components/schemas/WeightPerAxleGroup' width: description: Vehicle width, in centimeters. example: 2000 maximum: 5000 minimum: 0 type: integer type: object ServerErrorResponse: example: action: Correct arrival time of 'vehicle' to be earlier than its departure cause: Vehicle's arrival time is earlier than its departure time code: E613420 correlationId: fee3c453-f537-49ca-a285-f5f076bce7d1 status: 400 title: BAD_REQUEST properties: action: description: Provides actionable instructions on how to resolve this error. type: string cause: description: "Provides a human-readable description of the error and its cause to help you understand what went wrong \nand how to address the issue.\n" type: string code: description: "Provides a machine-readable error code that identifies the specific service error \nfor debugging and logging purposes.\n" type: string correlationId: description: "Provides the unique ID of the request that triggered this error. \nInclude this ID when contacting support for assistance.\n" type: string status: description: Indicates the HTTP status code, which matches the HTTP response status code. type: integer title: description: Provides the error title. type: string required: - title - status - code - cause - action - correlationId type: object ShiftIndex: default: 0 description: 'Index of a vehicle shift used to distinguish between different shifts for the same vehicle. Since a vehicle can have at most 7 shifts, the value must be between 0 and 6. The shift index identifies which shift in the vehicle type''s shifts array a tour corresponds to, allowing the same vehicle to operate across multiple time periods. For more information, see [Include multiple shifts](https://docs.here.com/tour-planning/docs/multiple-shifts).' example: 0 maximum: 6 minimum: 0 type: integer TieBreak: description: '**ALPHA** A hierarchical objective that allows ties in a higher-level objective to be broken by a lower-level objective' properties: objectives: items: $ref: '#/components/schemas/TieBreakObj' minItems: 2 type: array type: enum: - tieBreak example: tieBreak type: string required: - objectives - type type: object x-maturity: alpha HouseKeysBoundedSumStrategy: description: Takes a bounded sum (sum with upper limit) for all activities with the same house key. example: maximum: 600 type: boundedSum properties: maximum: $ref: '#/components/schemas/Duration' description: The upper limit for the total duration in seconds. type: enum: - boundedSum example: boundedSum type: string required: - maximum - type type: object x-maturity: alpha ScooterProfile: description: 'Routing calculations for scooters. The `departureTime` property allows to specify a custom date-time for which `traffic optimization` in routing calculations shall be performed. See `fleet.traffic` for details.' properties: avoid: $ref: '#/components/schemas/AvoidRoutes' departureTime: $ref: '#/components/schemas/DateAndTime' exclude: $ref: '#/components/schemas/Exclude' ignoreRouteViolations: $ref: '#/components/schemas/IgnoreRouteViolations' matrix: $ref: '#/components/schemas/Matrix' matrixId: $ref: '#/components/schemas/MatrixId' name: $ref: '#/components/schemas/ProfileName' options: $ref: '#/components/schemas/ScooterOptions' traffic: $ref: '#/components/schemas/Traffic' type: enum: - scooter example: scooter type: string violationMapping: $ref: '#/components/schemas/ViolationMapping' required: - name - type type: object TaxiOptions: description: Specifies taxi profile options. properties: allowDriveThroughTaxiRoads: default: true description: 'Specifies if a vehicle is allowed to drive through the taxi-only roads and lanes. It''s still allowed on taxi roads after the route start and before the destination even if not allowed to drive through the taxi-only roads.' example: true type: boolean axleCount: description: Specifies the total number of axles the vehicle has, i.e., axles on the base vehicle and any attached trailers. example: 2 format: int32 maximum: 255 minimum: 2 type: integer speedCap: $ref: '#/components/schemas/SpeedCap' trailerCount: description: 'The number of trailers attached to the vehicle. **Limitations:** Considered for route calculation for restrictions, but not for speed limits.' example: 0 format: int32 maximum: 1 minimum: 0 type: integer required: - allowDriveThroughTaxiRoads type: object BalanceDuration: description: '**ALPHA** An objective to balance duration across all tours.' properties: options: $ref: '#/components/schemas/BalanceOptions' type: enum: - balanceDuration example: balanceDuration type: string required: - options - type type: object x-maturity: alpha OptimizeTaskOrder: deprecated: true description: 'Deprecated, please use OptimizeTaskPosition objective instead. An objective to control order of job task activities in the tour. When specified, the task order is considered as a soft constraint and the solver tries to minimize amount of its violations.' properties: type: enum: - optimizeTaskOrder example: optimizeTaskOrder type: string required: - type type: object MixingRestrictionSet: description: A set of restrictions on mixing jobs based on their categories properties: compartments: description: '**ALPHA** An optional list of compartments, * if set, restrictions apply to listed compartments, separately for each one, * if not set, restrictions apply to the whole vehicle This currently works only for Tour level restrictions' items: $ref: '#/components/schemas/Id' maxItems: 10 minItems: 1 type: array x-maturity: alpha conflictingCategories: description: Represents a set of conflicting job categories. example: - food - non-food items: $ref: '#/components/schemas/Category' maxItems: 100 minItems: 2 type: array uniqueItems: true type: object VehicleFixedDutyRestTime: description: '**ALPHA** Defines type of duty rest time configuration with fixed duration Disclaimer: This is an experimental feature under development To enable it, add `restTimes` flag to `experimentalFeatures` configuration in the problem.' properties: canStartEarly: default: false description: 'Determines whether the break can start earlier than required. This allows for more optimal breaks allocation in order to minimize wait time.' example: true type: boolean maxDrivingTime: description: A max driving duration per duty/day in seconds example: 16200 format: int64 maximum: 604800 minimum: 14400 type: integer maxWorkingTime: description: A max working duration per duty/day in seconds example: 16200 format: int64 maximum: 604800 minimum: 14400 type: integer minOffTime: allOf: - $ref: '#/components/schemas/Duration' description: A minimum time between consecutive working days/duties in seconds maximum: 172800 minimum: 3600 type: enum: - fixedDuration example: fixedDuration type: string required: - minOffTime - type type: object x-maturity: alpha ParkingPlace: description: '**ALPHA** Specifies parking place data.' example: duration: 120 location: lat: 52.53088 lng: 13.38471 vehicleTypeIds: - truck1 properties: duration: $ref: '#/components/schemas/Duration' location: $ref: '#/components/schemas/RoutingLocation' vehicleTypeIds: items: $ref: '#/components/schemas/Id' minItems: 1 type: array uniqueItems: true required: - duration type: object x-maturity: alpha LinearPenalty: description: '**ALPHA** Linear penalty function that increases at a constant rate for each unit of time deviation from the preferred time window. This penalty type imposes costs immediately and consistently for any deviation, maintaining strict adherence to the schedule. Suitable for scenarios where minor delays are acceptable but should be minimized, such as grocery delivery or passenger pickup.' properties: type: enum: - linear example: linear type: string required: - type type: object x-maturity: alpha VehicleFixedDurationRestTime: description: '**BETA** Defines type of rest time configuration with fixed duration' properties: breakDuration: allOf: - $ref: '#/components/schemas/Duration' maximum: 172800 minimum: 60 interval: description: Determines after how long (in seconds) the break should occur example: 16200 format: int64 maximum: 604800 minimum: 1800 type: integer type: enum: - fixedDuration example: fixedDuration type: string required: - interval - breakDuration - type type: object x-maturity: beta TunnelCategory: description: 'Specifies the tunnel category to restrict certain route streets. The route will pass only through tunnels of a less strict category.' enum: - B - C - D - E type: string SpeedCap: description: 'Specifies the maximum speed, in m/s, which the vehicle should not exceed. This parameter affects route duration. Notes: * Car and Truck profile updates route ETA. * Scooter profile updates route optimization and ETA.' example: 20 format: double maximum: 70 minimum: 1 type: number AvoidZone: description: 'A routing zone identifier that routes will avoid going through. For example the identifier here:cm:envzone:2 references the Berlin Umweltzone environmental zone. For more information about the environmental zones, please have a look at [Here Content Map](https://developer.here.com/documentation/here-map-content/dev_guide/topics-attributes/environmental-zones.html)' example: here:cm:envzone:2 pattern: ^[A-Za-z0-9-]+:[A-Za-z0-9-]+:envzone:[0-9]+$ type: string Shared: description: '**ALPHA** Represents a set of shared resources, such as parking places and charging stations, that can be utilized by multiple vehicles during their tours.' properties: chargingStations: description: 'A list of charging stations with id that vehicles can use during their tours. If no stations are provided Tour Planning pulls in compatible stations defined in HERE content.' items: $ref: '#/components/schemas/ChargingStation' maxItems: 20 minItems: 1 type: array parking: description: A list of parking places with id that vehicles can use during their tours. items: $ref: '#/components/schemas/Parking' minItems: 1 type: array type: object x-maturity: alpha BusProfile: description: Route calculation for buses that are allowed to drive through the bus-only roads. properties: avoid: $ref: '#/components/schemas/AvoidRoutes' departureTime: $ref: '#/components/schemas/DateAndTime' exclude: $ref: '#/components/schemas/Exclude' ignoreRouteViolations: $ref: '#/components/schemas/IgnoreRouteViolations' matrix: $ref: '#/components/schemas/Matrix' matrixId: $ref: '#/components/schemas/MatrixId' name: $ref: '#/components/schemas/ProfileName' options: $ref: '#/components/schemas/BusOptions' traffic: $ref: '#/components/schemas/Traffic' type: enum: - bus example: bus type: string violationMapping: $ref: '#/components/schemas/ViolationMapping' required: - name - type type: object VehicleDrivingRestTime: description: '**BETA** Defines driving rest time' discriminator: mapping: fixedDuration: '#/components/schemas/VehicleFixedDurationRestTime' propertyName: type oneOf: - $ref: '#/components/schemas/VehicleFixedDurationRestTime' x-maturity: beta BusOptions: description: 'Specifies bus profile options. Supported only if the locations'' distribution radius is less than 490 km. If not added, only generic bus restrictions are applied and the fastest speed category is considered.' properties: axleCount: description: 'Specifies the total number of axles the vehicle has, i.e., axles on the base vehicle and any attached trailers.' example: 3 format: int32 maximum: 255 minimum: 2 type: integer grossWeight: description: Total vehicle weight, including trailers and shipped goods, in kilograms. example: 1000 minimum: 0 type: integer height: description: Vehicle height, in centimeters. example: 3000 maximum: 5000 minimum: 0 type: integer length: description: Vehicle length, in centimeters. example: 6000 maximum: 30000 minimum: 0 type: integer shippedHazardousGoods: items: $ref: '#/components/schemas/ShippedHazardousGoods' type: array speedCap: $ref: '#/components/schemas/SpeedCap' trailerCount: description: The number of trailers attached to the vehicle. example: 0 format: int32 maximum: 255 minimum: 0 type: integer tunnelCategory: $ref: '#/components/schemas/TunnelCategory' weightPerAxle: description: 'Vehicle weight per axle, in kilograms. **Note:** `weightPerAxle` and `weightPerAxleGroup` are incompatible.' example: 500 minimum: 0 type: integer weightPerAxleGroup: $ref: '#/components/schemas/WeightPerAxleGroup' width: description: Vehicle width, in centimeters. example: 2000 maximum: 5000 minimum: 0 type: integer type: object ViolationMappingItem: description: 'Generic base type for violation mappings. Violation mappings belong to either of two categories. Mappings belonging to the same category are evaluated together and if they apply, it is reflected in the errorCodes of the resulting matrix. Two types of mappings are supported: violated restrictions or traffic blockages. These cannot be combined into a single violation mapping item; each item must belong to one specific type.' discriminator: mapping: avoidAreasAndSegments: '#/components/schemas/ViolationMappingItemAvoidAreasAndSegments' restriction: '#/components/schemas/ViolationMappingItemRestriction' traffic: '#/components/schemas/ViolationMappingItemTraffic' propertyName: type oneOf: - $ref: '#/components/schemas/ViolationMappingItemRestriction' - $ref: '#/components/schemas/ViolationMappingItemTraffic' - $ref: '#/components/schemas/ViolationMappingItemAvoidAreasAndSegments' MaximizePriorityJobs: description: '**ALPHA** An objective to maximize assignment of prioritized jobs.' properties: type: enum: - maximizePriorityJobs example: maximizePriorityJobs type: string required: - type type: object x-maturity: alpha ExcessCosts: description: '**BETA** Specifies limits on distance, stops count etc. Penalties have to be paid in case those limits are violated.' properties: distance: $ref: '#/components/schemas/ExcessCostsField' duration: $ref: '#/components/schemas/ExcessCostsField' stops: $ref: '#/components/schemas/ExcessCostsField' waitingTime: $ref: '#/components/schemas/ExcessCostsField' type: object x-maturity: beta VehicleBreakPolicy: description: "Specifies the policy for vehicle break.\n * `allowAtTheEnd`: The vehicle break will be scheduled even if the vehicle arrives at the depot before the break's time window ends.\n\nThe break will be inserted prior to the arrival activity. By default, if a vehicle completes a tour before the end of the break, it is not added to the tour." enum: - allowAtTheEnd type: string Schedule: description: Specifies the expected `arrival` and `departure` times at a particular stop. properties: arrival: $ref: '#/components/schemas/DateAndTime' departure: $ref: '#/components/schemas/DateAndTime' required: - arrival - departure type: object HouseKeysConfig: description: '**ALPHA** Configures the house keys feature which controls how service time is calculated when multiple jobs with the same `houseKeyId` are served at the same stop.' properties: defaultStrategy: $ref: '#/components/schemas/HouseKeysStrategy' description: The default strategy applied to all house key groups. required: - defaultStrategy type: object x-maturity: alpha BalanceActivities: description: '**ALPHA** An objective to balance activities across all tours.' properties: options: $ref: '#/components/schemas/BalanceOptions' type: enum: - balanceActivities example: balanceActivities type: string required: - options - type type: object x-maturity: alpha Plan: description: '[Set of jobs](https://docs.here.com/tour-planning/docs/problem#plan) that need to be completed as part of a tour. This includes details such as job locations for pickups and deliveries, time windows for when these tasks should be performed, and any specific requirements or constraints related to completing each job according to specific business requirements.' properties: clustering: description: "This feature groups similar jobs into one or more clusters to ensure they are assigned to the same\nstop whenever possible, allowing them to be served together. Jobs are considered similar if they\nshare the same:\n\n * Job type (only `pickup` or `delivery` are supported)\n * Locations\n * Time windows\n * Skills\n * Demand dimensions\n\n**Note**: If a cluster violates any constraints, it is divided into smaller clusters.\nJobs with priority are excluded from clustering." properties: serviceTimeStrategy: $ref: '#/components/schemas/ServiceTimeStrategy' required: - serviceTimeStrategy type: object groups: description: '**BETA** [Job groups](https://docs.here.com/tour-planning/docs/group-jobs) help organize jobs based on specific criteria, ensuring that jobs within the same group are completed sequentially by the same vehicle. Grouping jobs also allows for designating Pick-Up and Drop-Off (PUDO) points, which are locations for storing or collecting goods for a specific job group.' items: $ref: '#/components/schemas/Group' minItems: 1 type: array x-maturity: beta houseKeys: allOf: - $ref: '#/components/schemas/HouseKeysConfig' description: '**ALPHA** Configures the house keys feature which controls how service time is calculated when multiple jobs with the same `houseKeyId` are served at the same stop.' x-maturity: alpha jobs: description: 'A list of jobs to be completed during the tour. Jobs consist of pickup tasks, delivery tasks, or a combination of both, assigned to vehicles. Each job may include a location, service duration, and demand (for example, volume, mass). Optional attributes include houseKeyId for multi-delivery or pickup, time windows, required skills, tags, territory IDs, group IDs, priority, and customer ID. The job limit is calculated by summing all pickup and delivery task locations. This total cannot exceed 500 tasks for the synchronous endpoint and 7000 tasks for the asynchronous endpoint.' items: $ref: '#/components/schemas/Job' minItems: 1 type: array relations: description: "Allows defining rules and order for completing jobs by specific vehicles during the [tour re-planning process](https://docs.here.com/tour-planning/docs/relations).\n\n**Note**:\n * The optimization algorithm does not check jobs within a relation for constraint violations.\n * Relations cannot be used with jobs having multiple pickups or deliveries." items: $ref: '#/components/schemas/Relation' maxItems: 1000 minItems: 1 type: array shared: allOf: - $ref: '#/components/schemas/Shared' x-maturity: alpha required: - jobs type: object JobPositionFirst: description: Puts the job task at the beginning of the tour, executed immediately after departure. properties: type: enum: - first example: first type: string required: - type type: object PrivateBusProfile: description: Route calculation for buses that are not allowed to drive through the bus-only roads. properties: avoid: $ref: '#/components/schemas/AvoidRoutes' departureTime: $ref: '#/components/schemas/DateAndTime' exclude: $ref: '#/components/schemas/Exclude' ignoreRouteViolations: $ref: '#/components/schemas/IgnoreRouteViolations' matrix: $ref: '#/components/schemas/Matrix' matrixId: $ref: '#/components/schemas/MatrixId' name: $ref: '#/components/schemas/ProfileName' options: $ref: '#/components/schemas/BusOptions' traffic: $ref: '#/components/schemas/Traffic' type: enum: - privateBus example: privateBus type: string violationMapping: $ref: '#/components/schemas/ViolationMapping' required: - name - type type: object WeightPerAxleGroup: description: 'Specifies the weights of different axle groups, like single and tandem axles. This allows specification of axle weights in a more fine-grained way than `weightPerAxle`. This is relevant in countries with signs and regulations that specify different limits for different axle groups, like the USA and Sweden. Weights are specified in kilograms (kg) and are the total weight of the axle group. **Note:** `weightPerAxleGroup` and `weightPerAxle` are incompatible.' example: single: 11000 tandem: 18000 properties: quad: description: quad axle group format: int32 minimum: 0 type: integer quint: description: quint axle group format: int32 minimum: 0 type: integer single: description: single axle group format: int32 minimum: 0 type: integer tandem: description: tandem axle group format: int32 minimum: 0 type: integer triple: description: triple axle group format: int32 minimum: 0 type: integer type: object JobPositionAny: description: 'Puts the job task at any place in the tour (also between ordered jobs) but not before the `first` position and not after the `last` position. This designation permits the API to position assignments within the tour anywhere between first and last assignments, optimizing the route for cost and time efficiency.' properties: type: enum: - any example: any type: string required: - type type: object HouseKeysMaxDurationStrategy: description: Takes max time duration from all activities and applies it once. example: type: maxDuration properties: type: enum: - maxDuration example: maxDuration type: string required: - type type: object x-maturity: alpha MaximizeTours: description: '**ALPHA** Maximizes the number of used vehicles.' properties: type: enum: - maximizeTours example: maximizeTours type: string required: - type type: object x-maturity: alpha RelationType: description: "Defines how jobs are related to each other and how they should be completed by a specific vehicle.\nThe following relation types are supported:\n * `sequence`: Jobs must be served by the vehicle in the specified order without changes or without\n inserting other jobs between them.\n * `flexible`: Jobs must be served in the provided order, but other jobs unspecified in the relation\n can be inserted between them.\n * `tour`: Jobs must be completed by the specified vehicle, but the order can be changed." enum: - sequence - tour - flexible example: sequence type: string VehicleWorkingRestTime: description: '**BETA** Defines working rest time' discriminator: mapping: fixedDuration: '#/components/schemas/VehicleFixedDurationRestTime' propertyName: type oneOf: - $ref: '#/components/schemas/VehicleFixedDurationRestTime' x-maturity: beta JobTask: description: 'Refers to a specific action within a job, such as picking up or delivering items at designated locations. Each job can include up to three pickup tasks and up to three delivery tasks, with each task having specific requirements and properties, such as demand (capacity requirements) and places (locations where the task is performed).' properties: demand: $ref: '#/components/schemas/Unit' order: deprecated: true description: 'Deprecated, use `position` instead. Job tasks with lower values of `order` are scheduled earlier in the route than job tasks with higher values of `order`.' example: 1 minimum: 1 type: integer places: items: $ref: '#/components/schemas/JobPlace' maxItems: 3 minItems: 1 type: array position: $ref: '#/components/schemas/JobPositionInTour' required: - places - demand type: object RoutingLocation: description: 'Represents a geographic location with coordinates and optional routing hints. Used to specify vehicle depot locations, job sites, break locations, charging stations, and other geographic points in tour planning. Includes latitude, longitude, optional location ID, optional side of street hint for preferred stopping side, and optional name hint to improve routing accuracy.' properties: id: allOf: - $ref: '#/components/schemas/Id' description: 'Specifies the location ID. Avoid referencing any sensitive or personal information, such as names, addresses, or information about a delivery or service. If specified and custom matrix provided, there is no need to pass latitude and longitude.' lat: description: Specifies the latitude coordinate in WGS-84 degrees. example: 52.53088 format: double maximum: 90 minimum: -90 type: number lng: description: Specifies the longitude coordinate in WGS-84 degrees. example: 13.38471 format: double maximum: 180 minimum: -180 type: number nameHint: description: 'Directs the route calculation to search for a location with a matching or similar name, improving routing accuracy when location names are known.' example: Friedrich-List-Straße type: string sideOfStreetHint: $ref: '#/components/schemas/SideOfStreetHint' type: object SoftTimeWindow: description: '**ALPHA** Represents a single soft constraint time window that allows flexibility when minor delays are acceptable. Consists of a hard constraint boundary (absolute time limits that cannot be exceeded) and a preferred time window (soft constraint), placed within the hard constrain boundary, for example: Example: ```markdown Absolute: 09:00 |---------------------------| 13:00 Preferred: 10:00 |-----------| 12:00 ``` Violations of the preferred time window are penalized but allowed, while violations of the hard boundary result in unassigned jobs. To enable this experimental feature, add the `softTimeWindows` flag to `experimentalFeatures` configuration in the problem. For more information, see [Set soft time windows](https://docs.here.com/tour-planning/docs/soft-time-windows).' properties: from: $ref: '#/components/schemas/SoftTime' to: $ref: '#/components/schemas/SoftTime' required: - from - to type: object x-maturity: alpha PolygonArea: description: 'A polygon defined as a list of coordinates. The polygon is automatically closed, so repeating the first vertex is not required.' properties: outer: description: List of coordinates defining the outline of the polygon. items: $ref: '#/components/schemas/Coordinate' maxItems: 100 minItems: 3 type: array type: enum: - polygon example: polygon type: string required: - outer - type type: object Tour: description: 'Represents a [pre-optimized route](https://docs.here.com/tour-planning/docs/solution#list-of-tours) that has been completed by a single vehicle, encompassing all assigned activities, such as pickups, deliveries, breaks, and so on.' properties: shiftIndex: $ref: '#/components/schemas/ShiftIndex' statistic: $ref: '#/components/schemas/Statistic' stops: description: 'The list of specific locations where a vehicle is scheduled to halt for various activities, such as pickups, deliveries, or breaks.' items: $ref: '#/components/schemas/Stop' type: array typeId: $ref: '#/components/schemas/Id' vehicleId: $ref: '#/components/schemas/Id' required: - vehicleId - typeId - stops - statistic - shiftIndex type: object UnassignedJobReason: description: 'Explains the circumstances under which a job was not assigned. For example, no vehicles with the required skill were available to complete the job.' properties: code: description: Specifies the reason code for a job that remains unassigned. example: SKILL_CONSTRAINT type: string description: description: Provides supplementary information to aid in identifying and resolving the underlying issue that caused the job to remain unassigned. example: cannot serve required skill type: string details: description: Provides more details about unassignment. items: $ref: '#/components/schemas/UnassignedJobDetail' minItems: 1 type: array required: - code - description type: object AvoidArea: description: 'Defines an explicit area to avoid/exclude when calculating the routes. Areas to be avoided/excluded can be specified by boundingBoxes or polygons (as encoded polyline or as list of geopts ). Notes: * Maximum count of polygons is 20. The combined total of boundingBoxes and polygons has a maximum limit of 250. * Minimum count of coordinates in any single polygon is 3. If less the corresponding error will be returned. * Maximum count of coordinates in any single polygon is 16. If more the corresponding error will be returned. * Self-intersecting polygons are not supported. If they are present in the request, the corresponding error will be returned.' discriminator: mapping: boundingBox: '#/components/schemas/BoundingBoxArea' encodedPolygon: '#/components/schemas/EncodedPolygonArea' polygon: '#/components/schemas/PolygonArea' propertyName: type oneOf: - $ref: '#/components/schemas/BoundingBoxArea' - $ref: '#/components/schemas/PolygonArea' - $ref: '#/components/schemas/EncodedPolygonArea' StopConfigurationLimits: description: '**ALPHA** Configures limits for a single stop. To enable it, add `clusterNearby` flag to `experimentalFeatures` configuration in the problem.' properties: maxIntraStopDistance: description: '**ALPHA** The maximum intra stop distance inside a single stop with more than one job related activity. If its not set, then only same location jobs can be clustered, with an exception for parking locations feature, where if you set the location for the parking than all job activities using this parking can be stacked regardless of intraStopDistance' example: 200 format: double maximum: 30000 minimum: 1 type: number type: object x-maturity: alpha ActivityType: description: The available types of planned tasks to be performed at a specific location and time as part of a stop. enum: - departure - arrival - pickup - delivery - break - drivingRestTime - workingRestTime - reload - pudo - dutyDrivingRestTime - dutyWorkingRestTime - recharge - backToVehicle example: delivery type: string MultiObjective: description: '**ALPHA** Enables the definition of multiple objectives with equal priority, ensuring that each objective is considered equally during the optimization process.' items: $ref: '#/components/schemas/AdvancedObjective' maxItems: 2 minItems: 1 type: array x-maturity: alpha AvoidFeatures: description: "A routing feature to avoid during route calculation. Available avoid feature options:\n * `tollRoad`\n * `motorway`\n * `ferry`\n * `tunnel`\n * `dirtRoad`\n * `controlledAccessHighway`\n * `carShuttleTrain`\n * `seasonalClosure`\n * `difficultTurns`: This option avoids difficult turns, sharp turns and U-turns on highways and motorways. It is only supported for the `truck` transport mode.\n * `uTurns`: This option avoids U-turns on highways and motorways. It is not supported for pedestrian, bicycle and scooter transport modes." enum: - tollRoad - motorway - ferry - tunnel - dirtRoad - controlledAccessHighway - carShuttleTrain - seasonalClosure - difficultTurns - uTurns example: tollRoad type: string CarProfile: description: 'Routing calculations for cars. The `departureTime` property allows to specify a custom date-time for which `traffic optimization` in routing calculations shall be performed. See `fleet.traffic` for details.' properties: avoid: $ref: '#/components/schemas/AvoidRoutes' departureTime: $ref: '#/components/schemas/DateAndTime' exclude: $ref: '#/components/schemas/Exclude' ignoreRouteViolations: $ref: '#/components/schemas/IgnoreRouteViolations' matrix: $ref: '#/components/schemas/Matrix' matrixId: $ref: '#/components/schemas/MatrixId' mode: default: fast description: "Specifies `route calculation` mode:\n- `fast`: Route calculation from start to destination optimized by travel time. In many cases, the route\n returned by the fast mode may not be the route with the fastest possible travel time. For example, the\n routing service may favor a route that remains on a highway, even if a faster travel time can be achieved\n by taking a detour or shortcut through an inconvenient side road.\n- `short`: Route calculation from start to destination disregarding any speed information. In this mode,\n the distance of the route is minimized, while keeping the route sensible. This includes, for example,\n penalizing turns. Due to that, the resulting route will not necessarily be the one with minimal distance." enum: - fast - short example: fast type: string name: $ref: '#/components/schemas/ProfileName' options: $ref: '#/components/schemas/CarOptions' traffic: $ref: '#/components/schemas/Traffic' type: enum: - car example: car type: string violationMapping: $ref: '#/components/schemas/ViolationMapping' required: - name - type type: object ErrorResponse: example: action: Correct arrival time of 'vehicle' to be earlier than its departure cause: Vehicle's arrival time is earlier than its departure time code: E613420 correlationId: fee3c453-f537-49ca-a285-f5f076bce7d1 status: 400 title: BAD_REQUEST properties: action: description: Provides actionable instructions on how to resolve this error. type: string cause: description: Human-readable explanation of the error and its cause. type: string code: description: "The error code consists of a fixed prefix (`E613`) followed by three digits that specify the error. \nWhen seeking assistance from the support team, provide the complete error code for effective troubleshooting. \nSee the [Developer Guide](https://docs.here.com/tour-planning/docs/api-errors) for more information and step-by-step guidance on resolving errors.\n\n| Code | Reason |\n| --------- | ---------------------------------------------------------------------------- |\n| `E613000` | General error |\n| `E613200` | Request schema validation error |\n| `E613201` | Problem definition validation error |\n| `E613202` | Too many job places |\n| `E613203` | Too many vehicle types |\n| `E613205` | Objectives and Advanced objectives are mutually exclusive |\n| `E613206` | Both order and position in the job task are present |\n| `E613207` | Both times and timeWindows in the job place are present |\n| `E613210` | Invalid truck height option |\n| `E613211` | Invalid truck width option |\n| `E613212` | Invalid truck length option |\n| `E613213` | Invalid max time option |\n| `E613214` | Invalid stagnation time option |\n| `E613215` | Break start time should be less than or equal to its end time |\n| `E613220` | Option conflicts with the used profile option |\n| `E613400` | Invalid region size |\n| `E613401` | Invalid coordinate specified in request |\n| `E613410` | More than one job has the same id |\n| `E613411` | Vehicle with given id does not exist |\n| `E613412` | Job cannot be served within vehicle time window |\n| `E613413` | Job has skill which cannot be served by vehicle |\n| `E613414` | Different dimensions for pickups and deliveries demand |\n| `E613415` | Pickup and delivery demand are incorrect: must be equal in one dimension |\n| `E613416` | Job specified in relation does not exist |\n| `E613417` | Job task has incorrect time window |\n| `E613418` | More than one vehicle type has the same id |\n| `E613420` | Vehicle's arrival time is earlier than its departure time |\n| `E613421` | Job assigned to more than one vehicle |\n| `E613422` | One of the vehicle's break times is outside of the vehicle's shift time |\n| `E613423` | Vehicle break used in relation must have location |\n| `E613425` | Profile names must be unique |\n| `E613426` | Unknown vehicle profile names in vehicle type definitions |\n| `E613427` | Multi job cannot be used within relation |\n| `E613428` | Ensure that all time windows have start and end date |\n| `E613429` | Region radius is too big to include traffic information |\n| `E613430` | Job task has overlapping time windows |\n| `E613431` | Both pickups and deliveries have to be set for the job with multiple tasks |\n| `E613432` | Truck gross weight is outside allowed range |\n| `E613433` | Truck weight per axle is outside allowed range |\n| `E613434` | Locations' distribution radius is too big for fleet profile type 'scooter' |\n| `E613435` | Locations' distribution radius is too big for profile option 'avoid' |\n| `E613436` | Time and distance costs cannot be both zero. If only one is provided it cannot be zero |\n| `E613437` | Locations' distribution radius is too big for using 'options' in fleet profile type 'truck' |\n| `E613438` | Time, used within vehicle, pudo or job, cannot be before Unix epoch |\n| `E613439` | Break should have non-empty time windows |\n| `E613440` | Invalid country code in exclude[countries] |\n| `E613441` | Region radius is too big for profile option 'exclude' |\n| `E613442` | More than one vehicle has the same id |\n| `E613443` | Invalid combination of `vehicleIds` and `amount` properties in vehicle type |\n| `E613444` | Jobs and pudos from one group cannot be mixed with another group in the relation |\n| `E613445` | Pudos and jobs in the relation should be added in correct order |\n| `E613446` | Pudos in the relation are duplicated |\n| `E613500` | Unsupported experimental feature flag |\n| `E613501` | Experimental feature is used without specifying the experimental flag. |\n| `E613600` | Vehicles' shifts overlap |\n| `E613601` | Relation has job with multiple places or time windows |\n| `E613604` | Redundant 'optimizeTaskOrder' objective |\n| `E613606` | Duplicate territory specified for the same vehicle |\n| `E613609` | Invalid 'shiftIndex' in relation |\n| `E613611` | Avoided polygon specified in vehicle profile has self intersection |\n| `E613612` | Same location with different 'sideOfStreetHint' attribute present in the problem |\n| `E613613` | Overlapping vehicle break time windows |\n| `E613614` | Same location with different 'nameHint' attribute present in the problem |\n| `E613615` | Missing 'minimizeUnassigned' objective |\n| `E613616` | Missing 'minimizeCost' objective |\n| `E613617` | Invalid combination of avoid feature `difficultTurns` or `uTurns` and transport mode. |\n| `E613618` | More breaks referenced in relations for a particular vehicle than defined in that vehicle's corresponding shift |\n| `E613619` | Min stops limit greater than max stops limit |\n| `E613620` | Locations' distribution radius is too big for fleet profile type 'bus' |\n| `E613621` | Locations' distribution radius is too big for fleet profile type 'privateBus' |\n| `E613622` | Locations' distribution radius is too big for using 'options' in fleet profile type 'car' |\n| `E613623` | Both break and rest time features are being used |\n| `E613624` | Different types of stop config used |\n| `E613625` | Only one vehicle profile can be used with custom matrix |\n| `E613626` | Custom matrix validation error |\n| `E613627` | Custom matrix does not contain all of specified in problem locations |\n| `E613628` | Invalid combination of `matrix` and other vehicle profile properties |\n| `E613629` | Missing 'optimizeTaskPosition' objective |\n| `E613630` | Location is incorrect |\n| `E613631` | Location types are mixed |\n| `E613632` | Custom matrix not provided with custom locations |\n| `E613633` | Same location 'id' with different coordinates present in the problem |\n| `E613634` | Visually appealing tours feature cannot be used with custom locations |\n| `E613635` | Minimize tour overlap feature cannot be used with custom locations |\n| `E613636` | Profiles array with matrixId is outside allowed range |\n| `E613637` | Profile property `matrixId` cannot be provided for sync endpoint |\n| `E613638` | Duplicate matrixId specified for other vehicle profile |\n| `E613639` | Incorrect matrixId used in the vehicle |\n| `E613640` | Custom matrix cannot be provided for async endpoint |\n| `E613649` | `weightPerAxle` and `weightPerAxleGroup` are mutually exclusive |\n| `E613650` | Locations' distribution radius is too big for profile type 'taxi' |\n| `E613651` | `fuel` cannot be used with `pedestrian` or `bicycle` profile |\n| `E613652` | Invalid configuration for rest times property |\n| `E613653` | `traffic` route violation can be ignored only for car and truck profiles |\n| `E613654` | Too many locations are placed on the same road section |\n| `E613655` | Unknown vehicle profile names in stopConfig definitions |\n| `E613656` | More than one parking has the same id |\n| `E613657` | Vehicle type id is defined for multiple parking places at the same location |\n| `E613658` | Multiple parking places with default vehicle type ids at the same location |\n| `E613659` | `violationMapping` with `type`:`restriction` must have at least one of (`grossWeight`, `currentWeight`, `height`) with a value of `include` or `ignore` |\n| `E613660` | `avoidAreasAndSegments` route violation can be ignored only for car and truck profiles |\n| `E613661` | `restriction` route violation can be ignored only for truck profiles |\n| `E613662` | `violationMapping` cannot be used together with `traffic` ignore violation |\n| `E613663` | The `all` option in `ignoreRouteViolations` cannot be used together with other options |\n| `E613664` | Region radius is too big for profile option 'violationMapping' |\n| `E613665` | `evProfileId` without `maxDistance` cannot be used with time-dependent VRP |\n| `E613666` | Charging stations are missing while using `maxDistance` in charging |\n| `E613667` | Locations' distribution radius is too big for using 'options' in fleet profile type 'pedestrian' |\n| `E613668` | Unknown stop profile names in VehicleShift definitions |\n| `E613669` | Invalid violation mapping configuration |\n| `E613670` | `evProfileId`, `minCharge` and `maxCharge` are required for consumption-based recharging |\n| `E613671` | Unknown profile in StopConfiguration definitions |\n| `E613673` | Parking with explicit location requires stop configuration on affected vehicle shifts |\n| `E613674` | `vehicleId` in `initialCharges` does not match any vehicle in the vehicle type |\n| `E613675` | Locations' distribution radius is too big for EV vehicles |\n| `E613676` | Initial charge in `initialCharges` must be greater than `minCharge` |\n| `E613677` | Duplicate `vehicleId` values are used in `initialCharges` |\n| `E613678` | EV vehicle types cannot mix `maxDistance` and energy consumption strategies |\n| `E613679` | More than one charging station has the same id |\n| `E613680` | Vehicle type id in `vehicleTypeToDuration` does not match any vehicle type |\n| `E613681` | The same evProfileId must not be used across different routing profiles |\n| `E613682` | Too many unique evProfileIds across the fleet |\n| `E613683` | Too many routing profiles used with EV charging |\n| `E613684` | `evProfileId` cannot be used with `pedestrian` or `bicycle` profile |\n| `E613685` | `evProfileId` cannot be used with a profile that has a custom inline matrix |\n| `E613686` | Time window start must be less than or equal to its end |\n| `E613687` | Vehicle must have either `capacity` or `compartments` set |\n| `E613688` | Mixing restrictions reference unknown compartments |\n| `E613689` | Compartments in mixing restrictions are supported only on tour level |\n| `E613690` | Duplicated compartment names in the vehicle |\n" type: string correlationId: description: "Provides the unique ID of the request that triggered this error. \nInclude this ID when contacting support for assistance.\n" type: string status: description: Indicates the HTTP status code, which matches the HTTP response status code. type: integer title: description: Provides the title of the error with a brief summary of the issue encountered. type: string required: - title - status - code - cause - action - correlationId type: object PudoPlace: description: '**BETA** Specifies the location and time for serving the pick-up and drop-off (PUDO) activity. This ensures that each PUDO is served at the correct location and within the designated time frame.' example: duration: 180 location: lat: 52.53088 lng: 13.38471 tag: some_tag times: - - '2020-07-04T10:00:00Z' - '2020-07-04T12:00:00Z' properties: duration: $ref: '#/components/schemas/Duration' location: $ref: '#/components/schemas/RoutingLocation' tag: $ref: '#/components/schemas/PlaceTag' timeWindows: items: $ref: '#/components/schemas/SoftTimeWindow' maxItems: 4 minItems: 0 type: array times: $ref: '#/components/schemas/TimeWindows' required: - location - duration type: object x-maturity: beta CostStatistics: description: 'Breakdown of cost into individual components. Fields are only present when the corresponding cost source is configured on the vehicle and the value is non-zero.' properties: distance: description: Cost from distance traveled. example: 19886.32 format: double minimum: 0 type: number excess: $ref: '#/components/schemas/ExcessCostStatistics' description: Excess costs from exceeding limits. Present only when excessCosts is configured on the vehicle. fixed: description: Fixed cost for using the vehicle. example: 100 format: double minimum: 0 type: number perJob: description: Cost from per-job cost function. Present only when perJob is configured on the vehicle. example: 2500 format: double minimum: 0 type: number perWaitingTime: description: Cost from waiting time. Present only when perWaitingTime is configured on the vehicle. example: 120 format: double minimum: 0 type: number time: description: Cost from time (duration minus waiting, or full duration if perWaitingTime is not configured). example: 7204.53 format: double minimum: 0 type: number type: object x-maturity: alpha VehicleType: description: Represents a vehicle type. properties: amount: deprecated: true description: 'Deprecated, use `vehicleIds` instead. Amount of vehicles available. Should be specified if `vehicleIds` array is not set.' example: 1 maximum: 350 minimum: 1 type: integer capacity: allOf: - $ref: '#/components/schemas/Unit' description: Specifies the capacity of the vehicle, either `capacity` of `compartments` must be set example: - 100 - 5 charging: $ref: '#/components/schemas/VehicleCharging' compartments: description: '**ALPHA** List of compartments for this vehicle If this is set, `capacity` will be ignored Note that either capacity of compartments must be set and if both are set, then capacity will be ignored and total capacity will be calculated as sum of compartments Requires `compartments` feature flag to be set' example: - capacity: - 5 - 200 name: compartmentA items: $ref: '#/components/schemas/Compartment' maxItems: 10 minItems: 1 type: array x-maturity: alpha costs: $ref: '#/components/schemas/VehicleCosts' fuel: $ref: '#/components/schemas/VehicleFuel' id: allOf: - $ref: '#/components/schemas/Id' description: 'Specifies id of the vehicle type. Avoid assigning real-life identifiers, such as vehicle license plate as the `id` of a vehicle.' example: vehicle1 limits: $ref: '#/components/schemas/VehicleLimits' profile: $ref: '#/components/schemas/ProfileName' shifts: items: $ref: '#/components/schemas/VehicleShift' maxItems: 7 minItems: 1 type: array skills: $ref: '#/components/schemas/Skills' speedFactor: description: 'This factor enables the adjustment of the vehicle speed relative to the standard speed, thereby altering the driving duration. For instance, when utilizing a speedFactor of 0.1, the speed is reduced to 10% of the normal, resulting in the vehicle taking 10 times longer to travel the same distance. Consider using realistic values for the speedFactor. This multiplier does not take into account actual speed limits imposed by the roads or any legal regulations.' example: 1 format: double maximum: 10 minimum: 0.1 type: number territories: description: 'Represents the vehicle''s territories with their priorities. In case a job contains more than one task, then for a vehicle to be able to serve that job, its territories should be a superset of the territories of all tasks in that job' properties: items: items: $ref: '#/components/schemas/Territory' type: array strict: default: true description: Determines whether a vehicle can serve jobs outside its territories (when false) or not example: true type: boolean required: - items type: object vehicleIds: $ref: '#/components/schemas/VehicleIds' required: - id - profile - costs - shifts type: object VehicleLimits: description: Contains constraints applied to a vehicle type. properties: maxDistance: description: Max distance in meters per shift. example: 20000 format: double maximum: 3000000 minimum: 1 type: number maxDrivingTime: description: Max driving time in seconds per shift. example: 21600 format: int64 maximum: 604800 minimum: 1 type: integer maxIntraStopDistance: description: '**ALPHA** Max intra-stop distance in meters per shift, accumulated over all stops.' example: 20000 format: double maximum: 3000000 minimum: 1 type: number x-maturity: alpha shiftTime: description: 'The property shiftTime defines the maximum allowed working time of a vehicle type. In case a break is defined for this particular vehicle type, the duration of the break should be added to the shiftTime. For instance, if a vehicle type has a shift of 8 hours and a 30 minutes break, the total shiftTime should be defined as 8 hours 30 minutes. The properties `start.time` and `end.time` on the VehicleShift define the lower and upper bounds of the time interval in which the vehicle''s shift must lie. Under no circumstances may a vehicle start working before `start.time` or finish working after `end.time`. The `start.time` and `end.time` can be imagined as the opening and closing times of a depot where the vehicle starts and ends its tour. `start.time` and `end.time` can override the defined `shiftTime`. That means, in case the time defined by the `shiftTime` property is longer than the time interval between `start.time` and `end.time` the maximum working time of the vehicle will be reduced and will not exceed that time interval.' example: 21600 format: double maximum: 604800 minimum: 1 type: number stops: $ref: '#/components/schemas/VehicleStopsLimit' type: object Duration: description: 'Represents a time duration in seconds. Used to specify service times at job locations, waiting times, driving times, breaks, and other time-based constraints in tour planning.' example: 180 format: int64 maximum: 604800 minimum: 0 type: integer MinimizeTours: description: '**ALPHA** Minimizes the number of used vehicles' properties: type: enum: - minimizeTours example: minimizeTours type: string required: - type type: object x-maturity: alpha VehicleInitialCharge: description: '**ALPHA** Specifies vehicle charging properties.' example: charge: 50 vehicleId: vehicle1_1 properties: charge: description: Current battery level (in percentage) for specific vehicle. format: int32 maximum: 100 minimum: 0 type: integer vehicleId: $ref: '#/components/schemas/Id' required: - vehicleId - charge type: object x-maturity: alpha FixedDurationStrategy: description: 'Sets the cluster''s total duration to a predefined value, regardless of individual job durations. This strategy helps in planning and optimizing service time for similar jobs, ensuring they are completed within a predefined timeframe.' example: duration: 3600 type: fixedDurationStrategy properties: duration: description: The total duration of all jobs in a cluster, expressed in seconds. format: int64 type: integer type: enum: - fixedDurationStrategy example: fixedDurationStrategy type: string required: - duration - type type: object Unit: description: 'Represents multidimensional units of measure for vehicle capacity and job demand. Can specify volume, mass, weight, number of items, or other accumulative measures. Values at corresponding array positions are compared element-by-element during capacity validation. For example, `[100, 50]` could represent 100 kg weight and 50 cubic units of volume. For more information, see [Solve the capacitated vehicle routing problem](https://docs.here.com/tour-planning/docs/capacitated-vrp).' example: - 100 - 5 items: maximum: 2147483647 minimum: 0 type: integer maxItems: 10 minItems: 1 type: array BalanceMaxLoad: description: '**ALPHA** An objective to balance max load across all tours.' properties: options: $ref: '#/components/schemas/BalanceOptions' type: enum: - balanceMaxLoad example: balanceMaxLoad type: string required: - options - type type: object x-maturity: alpha PedestrianOptions: description: Specifies pedestrian profile options. properties: speed: default: 1 description: 'Specifies the walking speed in meters per second (m/s). Influences the duration of walking segments along the route.' example: 1 format: double maximum: 2 minimum: 0.5 type: number type: object RouteDetails: description: '**ALPHA** Represents the specific information about the path a vehicle takes between the current stop and the previous one, in the form of a [polyline representation of the route](https://docs.here.com/tour-planning/docs/polylines).' properties: polyline: description: 'A line string in the [flexible polyline](https://github.com/heremaps/flexible-polyline) format, which includes coordinates in the WGS84 coordinate system. If elevation data are present, it will be included. These route details can be used to visualize the route on a map.' example: BGot1nvC729hQoWnKgFvCsEjDwCjDoBrEAzF7BjInLnuB_JrnBnL3rB7BvH3Nz8B7GzZvHjczFnVrE3X8BTwgBnG8LjDjDrOrEjSnGnaxBpF type: string type: object SoftTime: description: '**ALPHA** Represents a single soft time window instance where time unit is defined in the RFC3339 format.' properties: penalty: $ref: '#/components/schemas/Penalty' preferred: allOf: - $ref: '#/components/schemas/DateAndTime' description: 'The preferred (soft constraint) time boundary that can be exceeded. Violations of this preferred time are allowed but result in penalties applied during optimization to minimize deviations.' time: allOf: - $ref: '#/components/schemas/DateAndTime' description: 'The hard constraint time boundary that cannot be exceeded. This represents the absolute time limit for the activity - exceeding this time results in the job being unassigned.' required: - time type: object x-maturity: alpha AuthErrorResponse: properties: error: description: Error message corresponding to the status code. example: Unauthorized type: string error_description: description: Detailed information about authentication or authorization errors. example: Invalid client credentials type: string required: - error - error_description type: object SideOfStreetHint: description: 'Provides a hint indicating the preferred side of the street for a job location. This ensures vehicles stop on the most convenient or safest side of the road to perform the delivery or pickup. The hint is a geographic point next to the street where the vehicle should stop. All locations with the same coordinates must have the same side of street attribute. For more information, see [Optimize routes with side-of-street preferences](https://docs.here.com/tour-planning/docs/side-of-street).' properties: lat: description: Specifies the latitude coordinate in WGS-84 degrees of the preferred stopping point. example: 52.53088 format: double maximum: 90 minimum: -90 type: number lng: description: Specifies the longitude coordinate in WGS-84 degrees of the preferred stopping point. example: 13.38471 format: double maximum: 180 minimum: -180 type: number matchSideOfStreet: default: onlyIfDivided description: 'Determines how strictly the side of street hint should be applied during route calculation. * `always`: Always use the side of street hint for this location * `onlyIfDivided`: Only use the side of street hint when the road is divided (default) For more information, see [Optimize routes with side-of-street preferences](https://docs.here.com/tour-planning/docs/side-of-street).' enum: - always - onlyIfDivided example: onlyIfDivided type: string required: - lat - lng type: object ProfileName: description: 'Specifies the name of the profile. Avoid assigning real-life identifiers, such as a vehicle license plate Id or personal name as the `profileName` of the routing profile.' example: normal_car maxLength: 128 minLength: 1 pattern: ^[a-zA-Z0-9_-]+$ type: string VehicleMinStopsCountLimit: description: '**ALPHA** Hard limit on the minimum number of stops in a shift. Please consult the developer guide for more information before using this feature. To enable it, add `minStops` flag to `experimentalFeatures` configuration in the problem.' properties: value: description: The minimum number of stops allowed in a vehicle shift. example: 1 minimum: 0 type: integer required: - value type: object x-maturity: alpha TimeWindows: description: 'Represents multiple hard constraint time windows. Each time window specifies a time period during which an activity (such as a delivery or pickup) must start. No violations are allowed - if a job cannot be served within any of the specified time windows, it might remain unassigned. For more information, see [Limit the start time of activities through time windows](https://docs.here.com/tour-planning/docs/time-windows).' example: - - '2020-07-04T08:00:00Z' - '2020-07-04T10:00:00Z' - - '2020-07-04T16:00:00Z' - '2020-07-04T18:00:00Z' items: $ref: '#/components/schemas/TimeWindow' maxItems: 4 minItems: 0 type: array TimeWindow: description: 'Represents a single hard constraint time window. The first element is the lower bound (earliest start time) and the second element is the upper bound (latest start time) in RFC3339 format. The job task must begin within this time window or the job may remain unassigned.' example: - '2020-07-04T08:00:00Z' - '2020-07-04T10:00:00Z' items: $ref: '#/components/schemas/DateAndTime' maxItems: 2 minItems: 2 type: array QuadraticPenalty: description: '**ALPHA** Quadratic penalty function that increases exponentially with larger deviations from the preferred time window. Provides flexibility for small delays but strongly discourages large deviations. Suitable for time-sensitive scenarios where lateness has serious consequences, such as medical deliveries, perishable goods transport, or executive transport.' properties: type: enum: - quadratic example: quadratic type: string required: - type type: object x-maturity: alpha Termination: description: Defines the conditions under which the optimization algorithm stops running. properties: maxTime: description: 'Sets the maximum duration (in seconds) the algorithm runs to solve a problem. If the algorithm doesn''t find a solution within this time, it stops and returns the best solution found so far. | Endpoint Type | Maximum Value (seconds) | Default Value (seconds) | |-------------------|--------------------------|-------------------------| | Synchronous | 300 | 240 | | Asynchronous | 18000 | 3600 |' example: 30 format: int64 minimum: 1 type: integer searchEffort: default: balanced description: '**ALPHA** Controls how aggressively the solver terminates when progress slows down. Defaults to "balanced" if omitted.' enum: - quick - balanced - thorough example: balanced type: string x-maturity: alpha stagnationTime: description: 'Specifies the duration (in seconds) the algorithm waits for an improved solution before stopping. If no better solution is found within this time, the algorithm terminates, which prevents wasting resources on minimal improvements. | Endpoint Type | Maximum Value (seconds) | Default Value (seconds) | |-------------------|--------------------------|-------------------------| | Synchronous | 240 | 10 | | Asynchronous | 18000 | 600 |' example: 5 format: int64 minimum: 1 type: integer required: - maxTime - stagnationTime type: object ViolationMapping: description: 'List of items for mapping certain violated restrictions to specific error codes in the matrix. This mapping can classify restrictions or blockages while still providing the resulting times and distances in the calculated matrix. Items are grouped into categories and evaluated collectively. Error codes are associated with the `category`, rather than being tied to individual restrictions or blockages. There are three distinct types of mappings: * violated restrictions * traffic-related blockages * violations when avoiding areas or individual segments These mappings must be maintained as separate violation mapping items, although they can belong to the same category. A violation mapping type can support additional parameters defining how a particular violation should be managed. There are three settings for these parameters: `include`: the violated restriction is added to a mapped category instead of causing a hard error code 3. `exclude`: the violated restriction is not added to a mapped category and still causes an error code 3. This is the default for height and grossWeight. `ignore`: the algorithm is not taking the restriction or property / attribute of the road into consideration. This is the default attribute for restrictions on bridge or time-dependent restrictions. The parameters for each mapping type are listed in the respective schema. Examples for mappings of different types as `category` 1: - map violations with violated height and violated grossWeight:
`{ "category": "category1", "type": "restriction", "grossWeight": "include", "height": "include" }` - map violations with violated height and NOT violated grossWeight:
`{ "category": "category1", "type": "restriction", "height": "include", "grossWeight": "exclude" }` - map violations with violated height, violation or non-violation of grossWeight doesn''t matter:
`{ "category": "category1", "type": "restriction", "height": "include", "grossWeight": "ignore" }` - map violations with violated height and violated currentWeight:
`{ "category": "category1", "type": "restriction", "height": "include", "currentWeight": "include" }` - map violations with violated height and NOT violated currentWeight:
`{ "category": "category1", "type": "restriction", "height": "include", "currentWeight": "exclude" }` - map violations with violated height, violation or non-violation of currentWeight doesn''t matter:
`{ "category": "category1", "type": "restriction","height": "include", "currentWeight": "ignore" }` - map violations of avoiding an area or a segment:
`{ "category": "category1", "type": "avoidAreasAndSegments" }` - map violations of traffic-related blockages outside of bridges:
`{ "category": "category1", "type": "traffic", "bridge": "exclude" }` Unless include or exclude is stated, grossWeight or height can be mapped regardless, if it is timeDependent or on a bridge. Please see `matrix` description in the response section for more information about error codes. If additional types of restrictions are supported for mapping in the future, they will default to "ignore" to ensure consistent results. A violation mapping item belongs to either of two categories. Mappings of type `traffic` or `avoidAreasAndSegments` are only supported for transport modes `car` and `truck`.' items: $ref: '#/components/schemas/ViolationMappingItem' maxItems: 10 minItems: 1 type: array uniqueItems: true JobPositionOrdered: description: 'In order of priority, puts the job task lower than `first` but higher than unordered and `last` tasks. Assignments labeled as `ordered` must also include an associated `position` value, represented by an integer equal to or greater than `1`. When multiple ordered assignments share the same `position` value, the API optimizes the route among them before proceeding.' properties: type: enum: - ordered example: ordered type: string value: example: 1 minimum: 1 type: integer required: - value - type type: object ExcessCostStatistics: description: 'Excess costs broken down by metric. Fields are only present when the corresponding limit is configured and the excess cost is non-zero.' properties: distance: description: Cost incurred for distance exceeding the configured limit. example: 50 format: double minimum: 0 type: number duration: description: Cost incurred for duration exceeding the configured limit. example: 30 format: double minimum: 0 type: number stops: description: Cost incurred for stop count exceeding the configured limit. example: 25 format: double minimum: 0 type: number waitingTime: description: Cost incurred for waiting time exceeding the configured limit. example: 15 format: double minimum: 0 type: number type: object x-maturity: alpha BalanceOptions: description: '**ALPHA** Specifies balance objective options. At the moment, it uses coefficient of variation as balancing measure.' properties: threshold: description: A balancing threshold specifies desired balancing level. Lower values can be ignored in favor of another objective. example: 0.5 format: double maximum: 1 minimum: 0 type: number required: - threshold type: object x-maturity: alpha MinimizeDistance: description: An objective to minimize total distance. properties: type: enum: - minimizeDistance example: minimizeDistance type: string required: - type type: object Skills: description: 'A list of skills required by a job or provided by a vehicle type. Only vehicles with all the skills required by a job can serve that job. Use skills to match specific vehicle capabilities to job requirements, such as `fridge` for refrigerated transport, `plumber` for service jobs, or `heavy_duty` for large loads. If no vehicle with matching skills has sufficient capacity or time, jobs requiring those skills will remain unassigned. For more information, see [Assign jobs based on skills](https://docs.here.com/tour-planning/docs/skills).' example: - fridge items: maxLength: 64 minLength: 1 pattern: ^[a-zA-Z0-9_-]+$ type: string maxItems: 100 minItems: 1 type: array MatrixOrigin: description: An ordered list of origins used in the routing matrix discriminator: mapping: id: '#/components/schemas/MatrixOriginId' propertyName: type oneOf: - $ref: '#/components/schemas/MatrixOriginId' TruckProfile: description: 'Route calculation for trucks. This mode considers truck limitations on links and uses different speed assumptions when calculating the route. The `departureTime` property allows to specify a custom date-time for which `traffic optimization` in routing calculations shall be performed. See `fleet.traffic` for details.' example: name: normal_truck type: truck properties: avoid: $ref: '#/components/schemas/AvoidRoutes' departureTime: $ref: '#/components/schemas/DateAndTime' exclude: $ref: '#/components/schemas/Exclude' ignoreRouteViolations: $ref: '#/components/schemas/IgnoreRouteViolations' matrix: $ref: '#/components/schemas/Matrix' matrixId: $ref: '#/components/schemas/MatrixId' name: $ref: '#/components/schemas/ProfileName' options: $ref: '#/components/schemas/TruckOptions' traffic: $ref: '#/components/schemas/Traffic' type: enum: - truck example: truck type: string violationMapping: $ref: '#/components/schemas/ViolationMapping' required: - name - type type: object CarOptions: description: Specifies car profile options. properties: axleCount: description: Specifies the total number of axles the vehicle has, i.e., axles on the base vehicle and any attached trailers. example: 2 format: int32 maximum: 255 minimum: 2 type: integer speedCap: $ref: '#/components/schemas/SpeedCap' trailerCount: description: 'The number of trailers attached to the vehicle. **Limitations:** Considered for route calculation for restrictions, but not for speed limits.' example: 0 format: int32 maximum: 1 minimum: 0 type: integer type: object Configuration: description: 'Provides a way to define various additional settings and constraints for solving vehicle routing problems or permit the use of experimental features. For more information, see [Configuration](https://docs.here.com/tour-planning/docs/configuration).' properties: experimentalFeatures: $ref: '#/components/schemas/ExperimentalFeatures' routeDetails: $ref: '#/components/schemas/RouteDetailsConfiguration' termination: $ref: '#/components/schemas/Termination' type: object responses: ForbiddenErrorResponse: description: The API key or authentication credentials do not allow you to access the requested resource. content: application/json: schema: $ref: '#/components/schemas/AuthErrorResponse' examples: errorResponseExample: $ref: '#/components/examples/ForbiddenErrorResponse' TooManyRequestsResponse: description: The number of API requests has exceeded the allowed limit within a specified time frame. content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsResponse' examples: errorResponseExample: $ref: '#/components/examples/TooManyRequestsResponse' headers: Retry-After: description: The value (in seconds) that indicates how long you must wait before making additional requests. schema: type: integer example: 5 X-RateLimit-Limit: description: "Indicates the maximum number of requests you can make within the specified time window (in seconds), \nformatted as \"number, number; w=window\".\n" schema: type: string example: 50, 50;w=10 X-RateLimit-Reset: description: Indicates (in seconds) how long you must wait before sending more requests. schema: type: integer example: 5 UnauthenticatedErrorResponse: description: The API key or authentication credentials are invalid or missing. content: application/json: schema: $ref: '#/components/schemas/AuthErrorResponse' examples: errorResponseExample: $ref: '#/components/examples/UnauthenticatedErrorResponse' ServerErrorResponse: description: An internal server error has occurred that prevents the API from processing the request. content: application/json: schema: $ref: '#/components/schemas/ServerErrorResponse' examples: errorResponseExample: $ref: '#/components/examples/ServerErrorResponse' examples: ServerErrorResponse: value: title: Server error status: 500 code: E613000 cause: Internal server error. action: '' correlationId: ff93d908-aecf-4df8-b9f6-3d33f85d638a UnauthenticatedErrorResponse: value: error: Unauthorized error_description: No credentials found TooManyRequestsResponse: value: error: Too Many Requests error_description: Rate limit for this service has been reached ForbiddenErrorResponse: value: error: Forbidden error_description: These credentials do not authorize access. headers: X-Request-Id: description: User-provided token that can be used to trace a request or a group of requests sent to the service. style: simple explode: false schema: type: string example: 8230d7ad-3f1c-4191-a8dd-f3c42026da89 X-Correlation-Id: description: An auto-generated identifier that uniquely distinguishes each request. style: simple explode: false schema: type: string example: 4199533b-6290-41db-8d79-edf4f4019a74 securitySchemes: ApiKey: type: apiKey name: apikey in: query description: "The API authentication key. For more information on how to get an API key, \nsee [Identity and Access Management - Developer Guide](https://docs.here.com/identity-and-access-management/docs/plat-using-apikeys).\n" Bearer: type: http scheme: bearer bearerFormat: JWT description: 'This token is obtained from a separate endpoint using client credentials and an OAuth 1.0a HMAC-SHA256 signed request. For more information on how to get a bearer token, see [OAuth 2.0 tokens](https://docs.here.com/identity-and-access-management/docs/how-to-authorize-with-oauth-20). ' externalDocs: description: The Developer guide and Release notes are available here. url: https://docs.here.com/tour-planning/docs/introduction-tour-planning