openapi: 3.2.0
info:
  title: Waypoints Sequence API
  description: Compute the best Sequence for Waypoints (Travelling Salesman Problem)
  termsOfService: https://developer.here.com/terms-conditions
  license:
    name: HERE Documentation License
    url: https://legal.here.com/en-gb/terms/documentation-license
  version: 8.3.3
servers:
- url: https://wps.hereapi.com
  description: Generated server url
security:
- apiKey: []
- bearerTokenAuth: []
tags:
- name: Waypoints Sequence
  description: Compute best Sequence for Waypoints (Travelling Salesman Problem)
paths:
  /v8/findsequence2:
    get:
      tags:
      - Waypoints Sequence
      description: 'Compute best Sequence for Waypoints (Travelling Salesman Problem).


        Note: We recommend using POST requests for large payloads, as GET requests may be constrained by request-line length limits imposed by load balancers.'
      operationId: Waypoints Sequence API findSequenceGET
      parameters:
      - name: start
        in: query
        description: Waypoint to start the sequence.<br/><br/>Example:<br/>&start=Munich;48.132777,11.565352
        required: true
        schema:
          type: string
      - name: end
        in: query
        description: 'Waypoint to be reached at the end of the sequence. Usage is optional, but recommended. The constraints st:, at:, acc:, heading:, sideOfStreetHint: described for destination parameters are available for this parameter.<br/><br/>Example:<br/>&end=Paris;48.857397,2.346642'
        required: false
        schema:
          type: string
      - name: mode
        in: query
        description: 'The routing mode determines how the route is calculated. <br/>Format: Type;TransportModes;TrafficMode;RouteFeature1,RouteFeature2<br/>Type can be `mode=fastest` or `mode=shortest`. <br/>  Available transport modes: `car`, `truck`, `bicycle`, `scooter`, `taxi`, `bus`, `pedestrian`. Note: `bicycle`, `bus`, and `taxi` modes are in beta and have limited functionality. <br/>To learn more about the available transport modes, see the [Transport modes documentation](https://www.here.com/docs/bundle/routing-api-developer-guide-v8/page/concepts/transport-modes.html) of HERE Routing API v8. <br/>RouteFeatures allow to avoid select road features to a certain degree. Available road features are: `tollroad`, `motorway`, `boatFerry`, `railFerry`, `tunnel`, `dirtRoad`. The use of these road features can be managed through setting values from the range of 0 to -3, where 0 is normal, unrestricted use, and -3 forces to strictly avoid the given feature. The delimiter between RouteFeatures is a comma. <br/>Example:<br/>&mode=fastest;car;traffic:disabled;motorway:-2<br/>&mode=fastest;car;traffic:enabled;motorway:-2,tollroad:-2'
        required: true
        schema:
          type: string
      - name: departure
        in: query
        description: 'Time when travel is expected to start. Traffic speed and incidents are taken into account when calculating the route. You can use now to specify the current time. Type: xs:dateTime.<br/><br/>Example:<br/>&departure=2021-07-04T17:00:00+02:00'
        required: false
        schema:
          type: string
      - name: hasTrailer
        in: query
        description: 'Does the vehicle tow a trailer? Values: true | false

          This parameter is deprecated. Use `trailersCount` instead.'
        required: false
        schema:
          type: string
      - name: trailersCount
        in: query
        description: 'Number of trailers or semi-trailers. For toll cost and truck restrictions.

          * Supported values: 0 - no trailer (default), 1 - one or more trailers, 2 - two or more trailers, 3 - three or more trailers, 4 - one or more semi-trailers.

          * `&trailersCount=4` is not supported for Waypoint Sequencing.'
        required: false
        schema:
          type: string
      - name: height
        in: query
        description: 'Actual height of the overall rigid/semi truck including trailers. Accepted value units are cm (centimeter), m (meter) or in (inch). Example: `350cm` or `3.5m` or `138in`. Applicable for truck restrictions and toll cost.'
        required: false
        schema:
          type: string
      - name: limitedWeight
        in: query
        description: 'Actual total weight of vehicle incl. payload and trailers/caravan including their payload.

          * Accepted value units are t (tons), kg (kilograms) or lbs (pounds).

          * Example: `7.5t` or `7500kg` or `16500lbs`.

          * Applicable for truck restrictions, speed profile selection, toll cost calculation and environmental zone restrictions. See also parameter `vehicleWeight`.

          * Note that country wide weight restrictions depend on the length, width, number of axles and trailers as well, so it might be necessary to specify these parameters as well.'
        required: false
        schema:
          type: string
      - name: shippedHazardousGoods
        in: query
        description: 'Comma separated list from supported values: `explosive`, `gas`, `flammable`, `combustible`, `organic`, `poison`, `radioActive`, `corrosive`, `poisonousInhalation`, `harmfulToWater`, `other`, `allhazardousGoods`, `explosiveFlammable`.

          * Applicable for toll cost calculation and truck restrictions.

          * For toll cost only values `explosive` and `other` are supported.

          * For Waypoints Sequence values `allhazardousGoods` and `explosiveFlammable` are not supported.'
        required: false
        schema:
          type: string
      - name: length
        in: query
        description: 'Length of the vehicle (including potential trailers).

          * Accepted value units are cm (centimeter), m (meter) or in (inch). Example: `1250cm` or `12.5m` or `492in`.

          * Applicable for toll cost calculation and truck restrictions.

          * Note that country wide length restrictions depend on the limitedWeight, width, number of axles and trailers as well, so it might be necessary to specify these parameters  as well.'
        required: false
        schema:
          type: string
      - name: weightPerAxle
        in: query
        description: 'Actual total weight per axle, incl. payload.

          * Accepted value units are t (tons), kg (kilograms) or lbs (pounds).

          * Example: `7.5t` or `7500kg` or `16500lbs`.

          * For Waypoints Sequence only supported unit is kg, without explicitly specifying unit.

          * Applicable for toll cost calculation and truck restrictions.'
        required: false
        schema:
          type: string
      - name: width
        in: query
        description: 'Width of the vehicle and trailer(s). Accepted value units are cm (centimeter), m (meter) or in (inch). Example: `350cm` or `3.5m` or `138in`. Applicable for truck restrictions. Note that country wide width restrictions depend on the limitedWeight, length, number of axles and trailers as well, so it might be necessary to specify these parameters as well.'
        required: false
        schema:
          type: string
      - name: tunnelCategory
        in: query
        description: 'Defines the tunnel categories the truck must NOT use. Supported values: `B`, `C`, `D` or `E`.

          * `A` tunnels have no restrictions.

          * `E` tunnels have most restrictions.

          * Example: If `&tunnelCategory=C` is specified, then route will use `A` and `B` tunnels but not `C`, `D` or `E`.'
        required: false
        schema:
          type: string
      - name: avoidSegments
        in: query
        description: 'Links which the route must not cross. The list of LinkIdTypes. LinkIdType is a xs:string with the following regular expression restrictions: [*-+]\d+<br/><br/>Example:<br/>&avoidSegments=here:cm:segment:190319503,here:cm:segment:192642784'
        required: false
        schema:
          type: string
      - name: avoidAreas
        in: query
        description: Areas which the route must not cross. Array of up to 20 BoundingBox-es.<br/><br/>Example with two bounding boxes:<br/>avoidAreas=52.517100760,13.3905424488;52.5169701849,13.391808451!52.517000760,13.3700424488;52.5168701849,13.371308451
        required: false
        schema:
          type: string
      - name: excludeCountries
        in: query
        description: A list of three-letter country codes (ISO-3166-1 alpha-3 code) to be excluded from the underlying route calculations. Excluding countries near or between waypoints may result in incalculable routes.
        required: false
        schema:
          type: string
      - name: avoidUTurns
        in: query
        description: 'This parameter avoid U-turns between destinations. To avoid U-turns at destinations use the parameter heading or sideOfStreetHints which are part of the destination parameters.<br/>This parameter is not supported for pedestrian, bicycle and scooter transport modes. Values: true/false. Default: false'
        required: false
        schema:
          type: string
      - name: improveFor
        in: query
        description: 'Measure to optimize. Values: distance,time. Default: time'
        required: false
        schema:
          type: string
      - name: jsonCallback
        in: query
        description: Specifies the function used to wrap the JSON response
        required: false
        schema:
          type: string
      - name: requestId
        in: query
        description: Request Id returned in the response to match it with the request
        required: false
        schema:
          type: string
          default: ''
      - name: restTimes
        in: query
        description: Activates the accounting for rest times. Rest times are modelled with a short and a long cycle. Both cycles consist of a driving phase and a resting phase..<br/>Also it can be specified if times at waypoint (service times) should be counted as <br/>restTimes=durations:{short driving time in seconds},{short rest time in seconds},{long driving time in seconds},{long rest time in seconds;serviceTimes:work|rest.<br/>Also the value can be set as default 'restTimes=default' which activates simplified European rules with 45min rest after 4.5h hours driving and 11h of long rest after 9h working, service times are accounted as work.<br/><br/>Example:<br/>&restTimes=durations:16200,2700,32400,39600;serviceTimes:work
        required: false
        schema:
          type: string
      - name: truckType
        in: query
        description: 'Truck routing only, specifies the vehicle type. Values:truck | tractorTruck, Defaults to truck. '
        required: false
        schema:
          type: string
      - name: walkSpeed
        in: query
        description: Sets the speed (m/s), if the routing mode comes with 'pedestrian'
        required: false
        schema:
          type: string
      - name: evChargingTimePerDistance
        in: query
        description: Activates accounting of times for charging electric vehicles. Requires a distance to be driven in Meter and the time in seconds required to recharge the energy required for the given distance.<br/><br/>Example:<br/>evChargingTimePerDistance=7200,250000
        required: false
        schema:
          type: string
      - name: clustering
        in: query
        description: 'The "clustering" parameter enables clustering of the waypoints. Two clustering algorithms are supported; drivingDistance and topologySegment. <br/>The algorithm drivingDistance is a connectivity-based clustering algorithm where all waypoints of a cluster are within a driving distance of 50 meters of the specified vehicle in both directions. A custom value of the driving distance can be specified by drivingDistance:distanceInMeter. Minimum allowed value for drivingDistance is 5 meters and maximum allowed value is 50000 meters. <br/>The algorithm topologySegment creates a cluster of waypoints that can be map-matched to the same topology segment. <br/><br/>Examples:<br/>&clustering=drivingDistance:100<br/>&clustering=topologySegment<br/><br/><b>Note: </b>Using this feature will incur an additional transaction.'
        required: false
        schema:
          type: string
      - name: driverCost
        in: query
        description: Cost per hour in arbitrary currency.
        required: false
        schema:
          type: string
      - name: vehicleCost
        in: query
        description: Cost per kilometer in arbitrary currency.
        required: false
        schema:
          type: string
      - name: breakTimes
        in: query
        description: 'Add comma separated fix time slots as break times, during which no stops or travel should be scheduled. Maximum number of breakTimes: 5. Format: xs:dateTime;duration of the break in seconds.<br/><br/>Example:<br/>`2023-03-13T12:00:00+02:00;3600,2023-03-13T16:00:00+02:00;1800`'
        required: false
        schema:
          type: string
      - name: apiKey
        in: query
        description: 'A key generated specifically to authenticate API requests. For more information on how to get an API key, see https://developer.here.com/documentation/identity-access-management/dev_guide/index.html .

          Other authentication options are Bearer token, see https://developer.here.com/documentation/identity-access-management/dev_guide/index.html or app_id with app_code for backward compatibility.'
        schema:
          type: string
      - name: destination0...destinationN
        in: query
        description: 'A waypoint contains an ID, WGS-84 coordinates, and constraints, which may impose certain restrictions when calculating the sequence.<br/>The format is `[ID;]latitude,longitude[;st:{time in seconds}[,interruptible:{true or false}]][[;acc:opening hours]|[;at:appointment]][;before:destinationNumber of other waypoint][;sideOfStreetHint:[matchSideOfStreet,]displayLatitude,displayLongitude]`.<br/><br/>The constraints are:<br/>`st`: Service time spent at the waypoint. Value in seconds should be between 0 and 604800 (one week). Example: `st:300`<br/>Service time also has an optional feature `interruptible`, which can be set to either true or false. When enabled (true), the service time can be interrupted by break times. Default value is true.<br/>Note: This feature can''t be used with the `clustering` parameter.<br/>Example: `st:300,interruptible:false`<br/>`at`: Defines appointment time. Requires the service time as the duration of the appointment. Example: `at:2021-11-15T16:00:00+02:00;st:1800`<br/>`acc`: Access time windows during which a destination can be visited, separated by commas. An access time window consists of start time (weekday, time, timezone) and end time pair with a pipe symbol divider, followed by mandatory service time value. Max number of time windows: seven. Example: `acc:mo12:00:00+02:00|fr18:00:00+02:00;st:900`<br/>`before`: Defines the destination that must be reached later. Format: `before:{''destination'' parameter name including the number}`. Example: `before:destination7` <br/>acc and at cannot be used together on the same destination. <br/>`sideOfStreetHint`: Specifies the preferred side of street where the waypoint should be placed. Typically, this is the display location of an address or a POI (point of interest) on the side of the road returned by HERE Geocoding and Search API v7. Consists of the optional parameter `matchSideOfStreet` and coordinates. <br/>The `matchSideOfStreet` parameter determines how the hint is handled. Possible values are: <br/>&nbsp; `always` - The hint is always used. <br/>&nbsp; `onlyIfDivided` - The hint is used on roads where traffic in opposite directions is divided by a physical barrier or it''s illegal to cross into the lanes going in the opposite direction. <br/>&nbsp; The default value for `matchSideOfStreet` is `onlyIfDivided` <br/>`heading`: The direction from which the waypoint must be approached or in which direction one must go when leaving the waypoint. Expressed in degrees clock-wise from north. Values outside the range are wrapped to the range.<br/><br/>For places found using HERE Geocoding and Search API v7, use the coordinates from the `access` property.<br/><br/>Examples:<br/>`&destination3=Berlin_appointment;52.51605,13.37691;at:2021-10-14T16:00:00+02:00;st:300`<br/>`&destination11=Bratislava_limited_access;48.154722,17.145556;acc:tu06:00:00+02:00|tu20:00:00+02:00;st:900,interruptible:false`<br/>`&destination12=long_servicetime;55.670449,12.5784912;st:7200`<br/>`&destination17=Malmo_before_Copenhagen;55.600289,12.995798;before:destination12`<br/>`&destination20=50.113029,8.683684;sideOfStreetHint:always,50.112970,8.683692`<br/>`&destination20=Bottrop;51.51936,6.95109;heading:135`<br/>`&destination24=multi_acc_windows;52.529967,13.489713;acc:fr08:30:00+02:00|fr11:00:00+02:00,fr13:30:00+02:00|fr17:00:00+02:00;st:60`<br/><br/>The maximum number of waypoints is 202, including the start and stop points.The maximum number of waypoints assigned to road segment is 50. Road segments are limited by junctions or an end of the road.If the latter limit is encountered, consider using clustering by topology segment, which can often remove this restriction depending on the road network''s topology in the area.'
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/WseResponse'
      summary: Waypoints sequence API find sequence GET
      x-summary-source: derived
    post:
      tags:
      - Waypoints Sequence
      description: Compute best Sequence for Waypoints (Travelling Salesman Problem). For POST requests, send the request parameters in an application/x-www-form-urlencoded request body instead of the query string.
      operationId: Waypoints Sequence API findSequencePOST
      parameters:
      - name: mode
        in: query
        description: 'The routing mode determines how the route is calculated. <br/>Format: Type;TransportModes;TrafficMode;RouteFeature1,RouteFeature2<br/>Type can be `mode=fastest` or `mode=shortest`. <br/>  Available transport modes: `car`, `truck`, `bicycle`, `scooter`, `taxi`, `bus`, `pedestrian`. Note: `bicycle`, `bus`, and `taxi` modes are in beta and have limited functionality. <br/>To learn more about the available transport modes, see the [Transport modes documentation](https://www.here.com/docs/bundle/routing-api-developer-guide-v8/page/concepts/transport-modes.html) of HERE Routing API v8. <br/>RouteFeatures allow to avoid select road features to a certain degree. Available road features are: `tollroad`, `motorway`, `boatFerry`, `railFerry`, `tunnel`, `dirtRoad`. The use of these road features can be managed through setting values from the range of 0 to -3, where 0 is normal, unrestricted use, and -3 forces to strictly avoid the given feature. The delimiter between RouteFeatures is a comma. <br/>Example:<br/>&mode=fastest;car;traffic:disabled;motorway:-2<br/>&mode=fastest;car;traffic:enabled;motorway:-2,tollroad:-2'
        required: true
        schema:
          type: string
      - name: departure
        in: query
        description: 'Time when travel is expected to start. Traffic speed and incidents are taken into account when calculating the route. You can use now to specify the current time. Type: xs:dateTime.<br/><br/>Example:<br/>&departure=2021-07-04T17:00:00+02:00'
        required: false
        schema:
          type: string
      - name: hasTrailer
        in: query
        description: 'Does the vehicle tow a trailer? Values: true | false

          This parameter is deprecated. Use `trailersCount` instead.'
        required: false
        schema:
          type: string
      - name: trailersCount
        in: query
        description: 'Number of trailers or semi-trailers. For toll cost and truck restrictions.

          * Supported values: 0 - no trailer (default), 1 - one or more trailers, 2 - two or more trailers, 3 - three or more trailers, 4 - one or more semi-trailers.

          * `&trailersCount=4` is not supported for Waypoint Sequencing.'
        required: false
        schema:
          type: string
      - name: height
        in: query
        description: 'Actual height of the overall rigid/semi truck including trailers. Accepted value units are cm (centimeter), m (meter) or in (inch). Example: `350cm` or `3.5m` or `138in`. Applicable for truck restrictions and toll cost.'
        required: false
        schema:
          type: string
      - name: limitedWeight
        in: query
        description: 'Actual total weight of vehicle incl. payload and trailers/caravan including their payload.

          * Accepted value units are t (tons), kg (kilograms) or lbs (pounds).

          * Example: `7.5t` or `7500kg` or `16500lbs`.

          * Applicable for truck restrictions, speed profile selection, toll cost calculation and environmental zone restrictions. See also parameter `vehicleWeight`.

          * Note that country wide weight restrictions depend on the length, width, number of axles and trailers as well, so it might be necessary to specify these parameters as well.'
        required: false
        schema:
          type: string
      - name: shippedHazardousGoods
        in: query
        description: 'Comma separated list from supported values: `explosive`, `gas`, `flammable`, `combustible`, `organic`, `poison`, `radioActive`, `corrosive`, `poisonousInhalation`, `harmfulToWater`, `other`, `allhazardousGoods`, `explosiveFlammable`.

          * Applicable for toll cost calculation and truck restrictions.

          * For toll cost only values `explosive` and `other` are supported.

          * For Waypoints Sequence values `allhazardousGoods` and `explosiveFlammable` are not supported.'
        required: false
        schema:
          type: string
      - name: length
        in: query
        description: 'Length of the vehicle (including potential trailers).

          * Accepted value units are cm (centimeter), m (meter) or in (inch). Example: `1250cm` or `12.5m` or `492in`.

          * Applicable for toll cost calculation and truck restrictions.

          * Note that country wide length restrictions depend on the limitedWeight, width, number of axles and trailers as well, so it might be necessary to specify these parameters  as well.'
        required: false
        schema:
          type: string
      - name: weightPerAxle
        in: query
        description: 'Actual total weight per axle, incl. payload.

          * Accepted value units are t (tons), kg (kilograms) or lbs (pounds).

          * Example: `7.5t` or `7500kg` or `16500lbs`.

          * For Waypoints Sequence only supported unit is kg, without explicitly specifying unit.

          * Applicable for toll cost calculation and truck restrictions.'
        required: false
        schema:
          type: string
      - name: width
        in: query
        description: 'Width of the vehicle and trailer(s). Accepted value units are cm (centimeter), m (meter) or in (inch). Example: `350cm` or `3.5m` or `138in`. Applicable for truck restrictions. Note that country wide width restrictions depend on the limitedWeight, length, number of axles and trailers as well, so it might be necessary to specify these parameters as well.'
        required: false
        schema:
          type: string
      - name: tunnelCategory
        in: query
        description: 'Defines the tunnel categories the truck must NOT use. Supported values: `B`, `C`, `D` or `E`.

          * `A` tunnels have no restrictions.

          * `E` tunnels have most restrictions.

          * Example: If `&tunnelCategory=C` is specified, then route will use `A` and `B` tunnels but not `C`, `D` or `E`.'
        required: false
        schema:
          type: string
      - name: avoidSegments
        in: query
        description: 'Links which the route must not cross. The list of LinkIdTypes. LinkIdType is a xs:string with the following regular expression restrictions: [*-+]\d+<br/><br/>Example:<br/>&avoidSegments=here:cm:segment:190319503,here:cm:segment:192642784'
        required: false
        schema:
          type: string
      - name: avoidAreas
        in: query
        description: Areas which the route must not cross. Array of up to 20 BoundingBox-es.<br/><br/>Example with two bounding boxes:<br/>avoidAreas=52.517100760,13.3905424488;52.5169701849,13.391808451!52.517000760,13.3700424488;52.5168701849,13.371308451
        required: false
        schema:
          type: string
      - name: excludeCountries
        in: query
        description: A list of three-letter country codes (ISO-3166-1 alpha-3 code) to be excluded from the underlying route calculations. Excluding countries near or between waypoints may result in incalculable routes.
        required: false
        schema:
          type: string
      - name: avoidUTurns
        in: query
        description: 'This parameter avoid U-turns between destinations. To avoid U-turns at destinations use the parameter heading or sideOfStreetHints which are part of the destination parameters.<br/>This parameter is not supported for pedestrian, bicycle and scooter transport modes. Values: true/false. Default: false'
        required: false
        schema:
          type: string
      - name: improveFor
        in: query
        description: 'Measure to optimize. Values: distance,time. Default: time'
        required: false
        schema:
          type: string
      - name: jsonCallback
        in: query
        description: Specifies the function used to wrap the JSON response
        required: false
        schema:
          type: string
      - name: requestId
        in: query
        description: Request Id returned in the response to match it with the request
        required: false
        schema:
          type: string
          default: ''
      - name: restTimes
        in: query
        description: Activates the accounting for rest times. Rest times are modelled with a short and a long cycle. Both cycles consist of a driving phase and a resting phase..<br/>Also it can be specified if times at waypoint (service times) should be counted as <br/>restTimes=durations:{short driving time in seconds},{short rest time in seconds},{long driving time in seconds},{long rest time in seconds;serviceTimes:work|rest.<br/>Also the value can be set as default 'restTimes=default' which activates simplified European rules with 45min rest after 4.5h hours driving and 11h of long rest after 9h working, service times are accounted as work.<br/><br/>Example:<br/>&restTimes=durations:16200,2700,32400,39600;serviceTimes:work
        required: false
        schema:
          type: string
      - name: truckType
        in: query
        description: 'Truck routing only, specifies the vehicle type. Values:truck | tractorTruck, Defaults to truck. '
        required: false
        schema:
          type: string
      - name: walkSpeed
        in: query
        description: Sets the speed (m/s), if the routing mode comes with 'pedestrian'
        required: false
        schema:
          type: string
      - name: evChargingTimePerDistance
        in: query
        description: Activates accounting of times for charging electric vehicles. Requires a distance to be driven in Meter and the time in seconds required to recharge the energy required for the given distance.<br/><br/>Example:<br/>evChargingTimePerDistance=7200,250000
        required: false
        schema:
          type: string
      - name: clustering
        in: query
        description: 'The "clustering" parameter enables clustering of the waypoints. Two clustering algorithms are supported; drivingDistance and topologySegment. <br/>The algorithm drivingDistance is a connectivity-based clustering algorithm where all waypoints of a cluster are within a driving distance of 50 meters of the specified vehicle in both directions. A custom value of the driving distance can be specified by drivingDistance:distanceInMeter. Minimum allowed value for drivingDistance is 5 meters and maximum allowed value is 50000 meters. <br/>The algorithm topologySegment creates a cluster of waypoints that can be map-matched to the same topology segment. <br/><br/>Examples:<br/>&clustering=drivingDistance:100<br/>&clustering=topologySegment<br/><br/><b>Note: </b>Using this feature will incur an additional transaction.'
        required: false
        schema:
          type: string
      - name: driverCost
        in: query
        description: Cost per hour in arbitrary currency.
        required: false
        schema:
          type: string
      - name: vehicleCost
        in: query
        description: Cost per kilometer in arbitrary currency.
        required: false
        schema:
          type: string
      - name: breakTimes
        in: query
        description: 'Add comma separated fix time slots as break times, during which no stops or travel should be scheduled. Maximum number of breakTimes: 5. Format: xs:dateTime;duration of the break in seconds.<br/><br/>Example:<br/>`2023-03-13T12:00:00+02:00;3600,2023-03-13T16:00:00+02:00;1800`'
        required: false
        schema:
          type: string
      - name: apiKey
        in: query
        description: 'A key generated specifically to authenticate API requests. For more information on how to get an API key, see https://developer.here.com/documentation/identity-access-management/dev_guide/index.html .

          Other authentication options are Bearer token, see https://developer.here.com/documentation/identity-access-management/dev_guide/index.html or app_id with app_code for backward compatibility.'
        schema:
          type: string
      requestBody:
        description: The start point and the destination0...destinationN list are the parameters that grow with the request size and should be sent in the body. Authentication and basic configuration parameters may remain in the query string.
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                start:
                  type: string
                  description: Waypoint to start the sequence.<br/><br/>Example:<br/>&start=Munich;48.132777,11.565352
                destination0...destinationN:
                  type: string
                  description: 'A waypoint contains an ID, WGS-84 coordinates, and constraints, which may impose certain restrictions when calculating the sequence.<br/>The format is `[ID;]latitude,longitude[;st:{time in seconds}[,interruptible:{true or false}]][[;acc:opening hours]|[;at:appointment]][;before:destinationNumber of other waypoint][;sideOfStreetHint:[matchSideOfStreet,]displayLatitude,displayLongitude]`.<br/><br/>The constraints are:<br/>`st`: Service time spent at the waypoint. Value in seconds should be between 0 and 604800 (one week). Example: `st:300`<br/>Service time also has an optional feature `interruptible`, which can be set to either true or false. When enabled (true), the service time can be interrupted by break times. Default value is true.<br/>Note: This feature can''t be used with the `clustering` parameter.<br/>Example: `st:300,interruptible:false`<br/>`at`: Defines appointment time. Requires the service time as the duration of the appointment. Example: `at:2021-11-15T16:00:00+02:00;st:1800`<br/>`acc`: Access time windows during which a destination can be visited, separated by commas. An access time window consists of start time (weekday, time, timezone) and end time pair with a pipe symbol divider, followed by mandatory service time value. Max number of time windows: seven. Example: `acc:mo12:00:00+02:00|fr18:00:00+02:00;st:900`<br/>`before`: Defines the destination that must be reached later. Format: `before:{''destination'' parameter name including the number}`. Example: `before:destination7` <br/>acc and at cannot be used together on the same destination. <br/>`sideOfStreetHint`: Specifies the preferred side of street where the waypoint should be placed. Typically, this is the display location of an address or a POI (point of interest) on the side of the road returned by HERE Geocoding and Search API v7. Consists of the optional parameter `matchSideOfStreet` and coordinates. <br/>The `matchSideOfStreet` parameter determines how the hint is handled. Possible values are: <br/>&nbsp; `always` - The hint is always used. <br/>&nbsp; `onlyIfDivided` - The hint is used on roads where traffic in opposite directions is divided by a physical barrier or it''s illegal to cross into the lanes going in the opposite direction. <br/>&nbsp; The default value for `matchSideOfStreet` is `onlyIfDivided` <br/>`heading`: The direction from which the waypoint must be approached or in which direction one must go when leaving the waypoint. Expressed in degrees clock-wise from north. Values outside the range are wrapped to the range.<br/><br/>For places found using HERE Geocoding and Search API v7, use the coordinates from the `access` property.<br/><br/>Examples:<br/>`&destination3=Berlin_appointment;52.51605,13.37691;at:2021-10-14T16:00:00+02:00;st:300`<br/>`&destination11=Bratislava_limited_access;48.154722,17.145556;acc:tu06:00:00+02:00|tu20:00:00+02:00;st:900,interruptible:false`<br/>`&destination12=long_servicetime;55.670449,12.5784912;st:7200`<br/>`&destination17=Malmo_before_Copenhagen;55.600289,12.995798;before:destination12`<br/>`&destination20=50.113029,8.683684;sideOfStreetHint:always,50.112970,8.683692`<br/>`&destination20=Bottrop;51.51936,6.95109;heading:135`<br/>`&destination24=multi_acc_windows;52.529967,13.489713;acc:fr08:30:00+02:00|fr11:00:00+02:00,fr13:30:00+02:00|fr17:00:00+02:00;st:60`<br/><br/>The maximum number of waypoints is 202, including the start and stop points.The maximum number of waypoints assigned to road segment is 50. Road segments are limited by junctions or an end of the road.If the latter limit is encountered, consider using clustering by topology segment, which can often remove this restriction depending on the road network''s topology in the area.'
                end:
                  type: string
                  description: 'Waypoint to be reached at the end of the sequence. Usage is optional, but recommended. The constraints st:, at:, acc:, heading:, sideOfStreetHint: described for destination parameters are available for this parameter.<br/><br/>Example:<br/>&end=Paris;48.857397,2.346642'
            examples:
              waypoints:
                description: waypoints
                value: start=start;53.828,-1.618&destination0=d0;53.8462,-1.51051;st:180&destination1=d1;53.8456,-1.50877;st:180&end=end;53.845,-1.508
      responses:
        '200':
          description: OK
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/WseResponse'
      summary: Waypoints sequence API find sequence POST
      x-summary-source: derived
components:
  schemas:
    FailedConstraint:
      type: object
      properties:
        constraint:
          type: string
          description: The constraint reflects the input setting in the same format.
        reason:
          type: integer
          description: ' The reason defines why the constraint was not met: 0:Undetermined, 1:not reachable in time, 2:service time did not fit, 3: conflicts with arrival time of final waypoint.'
          format: int32
      description: List containing pairs of unmet constraints and reasons
    TimeBreakdown:
      type: object
      properties:
        driving:
          type: integer
          description: Time spent in motion for completing the sequence in seconds
          format: int32
        service:
          type: integer
          description: Active time spent at the waypoints in seconds
          format: int32
        rest:
          type: integer
          description: Time needed for resting according to legal regulations (simplified model) in seconds
          format: int32
        waiting:
          type: integer
          description: Time spent waiting at the waypoints in seconds
          format: int32
        break:
          type: integer
          description: Break time spent at the waypoint in seconds
          format: int32
      description: Time needed for traveling through the sequence by categories
    Warnings:
      type: object
      properties:
        outOfSequenceWaypoints:
          type: array
          description: 'List of waypoints that are out of sequence. Waypoints Sequence API computes an optimal sequence (order) of the waypoints. If some waypoints do not fit in that optimal sequence due to certain constraints violation then they will appear in this list. '
          xml:
            name: OutOfSequenceWaypoints
          items:
            $ref: '#/components/schemas/OutOfSequenceWaypoint'
        parameterOverrides:
          type: array
          description: 'List of parameters that are overridden. Mainly available for the ''pedestrian'' mode with traffic enabled requests.<br/> Example., if a request contains &mode=fastest;pedestrian;traffic:enabled; then it will be overridden and the response will have <br/> "parameterOverrides": [<br/>{<br/>"parameter": "mode",<br/>"userProvided": "fastest;pedestrian;traffic:enabled;",<br/>"overriddenBy": "fastest;pedestrian;traffic:disabled;"<br/>}<br/>]'
          xml:
            name: ParameterOverrides
          items:
            $ref: '#/components/schemas/ParameterOverride'
      description: This List contains 0 or more elements with an ordered list of waypoints. This value is set only, if no sequence is found due to constraints.
    WseResponse:
      type: object
      properties:
        results:
          type: array
          description: This List contains 1 or 0 elements with an ordered list of waypoints. This value is set, if a result is found.
          items:
            $ref: '#/components/schemas/Result'
        errors:
          type: array
          description: This field provides descriptions of errors which occurred during the calculation. The value is always included in the answer, but is a empty array, if there is no error. errors is providing information if the HTTP response code indicates an error.
          items:
            type: string
            description: This field provides descriptions of errors which occurred during the calculation. The value is always included in the answer, but is a empty array, if there is no error. errors is providing information if the HTTP response code indicates an error.
        processingTimeDesc:
          type: string
          description: Calculation time for the result, including the time unit. If the response does not contains an error, the processing time value is included.
        responseCode:
          type: string
          description: This value is set to the HTTP response code. If the parameter jsonCallback is set in the request, the HTTP response code is always 200. In this case this field gives the actual response code.
        warnings:
          $ref: '#/components/schemas/Warnings'
        requestId:
          type: string
          description: Identifier defined in the request and passed through the system. This field is null, if no such value was defined in the request.
      xml:
        name: Response
    Result:
      type: object
      properties:
        waypoints:
          type: array
          description: Waypoints in the order of the calculated sequence
          xml:
            name: Waypoints
          items:
            $ref: '#/components/schemas/Waypoint'
        distance:
          type: string
          description: Overall distance to travel the whole sequence in meter
          xml:
            name: Distance
        time:
          type: string
          description: Overall time to travel the whole sequence in seconds
        interconnections:
          type: array
          description: Timings and distances to travel from one waypoint to the next waypoint of the sequence
          items:
            $ref: '#/components/schemas/Interconnection'
        description:
          type: string
          description: Human readable description of the optimization goals
        timeBreakdown:
          $ref: '#/components/schemas/TimeBreakdown'
      description: This List contains 1 or 0 elements with an ordered list of waypoints. This value is set, if a result is found.
    Waypoint:
      type: object
      properties:
        id:
          type: string
          description: User provided id
        lat:
          type: number
          description: Latitude of the waypoint
          format: double
        lng:
          type: number
          description: Longitude of the waypoint
          format: double
        sequence:
          type: integer
          description: Position in the sequence
          format: int32
        estimatedArrival:
          type: string
          description: Expected time of arrival at the waypoint
        estimatedDeparture:
          type: string
          description: Expected time of departure from the waypoint, based on estimated arrival time and the service time at the waypoint
        fulfilledConstraints:
          type: array
          description: User specified constraints of the waypoint, which have been met
          items:
            type: string
            description: User specified constraints of the waypoint, which have been met
        cluster:
          type: integer
          description: 'ID of the cluster. Example, "cluster": 5'
          format: int32
      description: Waypoints in the order of the calculated sequence
    WseIssue:
      type: object
      properties:
        message:
          type: string
          description: Warning/error message
        code:
          type: integer
          description: Warning/error code
          format: int32
      description: 'Warnings for traveling between the two waypoints. Example: Route violates requested ''avoid'' options or legal/physical restrictions'
    OutOfSequenceWaypoint:
      type: object
      properties:
        id:
          type: string
          description: User provided id
        lat:
          type: number
          description: Latitude of the waypoint
          format: double
        lng:
          type: number
          description: Longitude of the waypoint
          format: double
        failedConstraints:
          type: array
          description: List containing pairs of unmet constraints and reasons
          items:
            $ref: '#/components/schemas/FailedConstraint'
      description: 'List of waypoints that are out of sequence. Waypoints Sequence API computes an optimal sequence (order) of the waypoints. If some waypoints do not fit in that optimal sequence due to certain constraints violation then they will appear in this list. '
    ParameterOverride:
      type: object
      properties:
        parameter:
          type: string
          description: Name of the parameter that is overridden.
        userProvided:
          type: string
          description: The value of the parameter as provided in the request.
        overriddenBy:
          type: string
          description: 'The value that has been used instead of the provided one in the request. Mainly available for the ''pedestrian'' mode with traffic enabled requests.<br/> Example., if a request contains &mode=fastest;pedestrian;traffic:enabled; then it will be overridden and the response will have <br/> "parameterOverrides": [<br/>{<br/>"parameter": "mode",<br/>"userProvided": "fastest;pedestrian;traffic:enabled;",<br/>"overriddenBy": "fastest;pedestrian;traffic:disabled;"<br/>}<br/>]'
      description: 'List of parameters that are overridden. Mainly available for the ''pedestrian'' mode with traffic enabled requests.<br/> Example., if a request contains &mode=fastest;pedestrian;traffic:enabled; then it will be overridden and the response will have <br/> "parameterOverrides": [<br/>{<br/>"parameter": "mode",<br/>"userProvided": "fastest;pedestrian;traffic:enabled;",<br/>"overriddenBy": "fastest;pedestrian;traffic:disabled;"<br/>}<br/>]'
    Interconnection:
      type: object
      properties:
        fromWaypoint:
          type: string
          description: Waypoint in the sequence that has been reached.
        toWaypoint:
          type: string
          description: Waypoint of the sequence to be reached next.
        distance:
          type: number
          description: Distance between the two waypoints.
          format: double
        time:
          type: number
          description: Time needed for traveling between the two waypoints.
          format: double
        break:
          type: number
          description: Break time spent at the destination in seconds
          format: double
        rest:
          type: number
          description: Rest time at or between the waypoints.
          format: double
        waiting:
          type: number
          description: Waiting time at the destination.
          format: double
        warnings:
          type: array
          description: 'Warnings for traveling between the two waypoints. Example: Route violates requested ''avoid'' options or legal/physical restrictions'
          items:
            $ref: '#/components/schemas/WseIssue'
      description: Timings and distances to travel from one waypoint to the next waypoint of the sequence
  securitySchemes:
    apiKey:
      type: apiKey
      description: A key generated specifically to authenticate API requests. For more information on how to get an API key, see [Identity and Access Management Developer Guide](https://www.here.com/docs/bundle/identity-and-access-management-developer-guide).
      name: apiKey
      in: query
    bearerTokenAuth:
      type: http
      description: A token 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 the [Identity and Access Management Developer Guide](https://www.here.com/docs/bundle/identity-and-access-management-developer-guide).
      scheme: bearer
      bearerFormat: JWT
externalDocs:
  description: The Developer guide and Release notes are available here.
  url: https://www.here.com/docs/category/waypoints-sequence-api-v8