Waypoint Sequencing

The waypoint sequence API optimizes the route within a given set of waypoints to get the shortest time or minimum distance.

Endpoints#

POST https://api.unl.global/v1/routing/sequence/{projectId}

GET https://api.unl.global/v1/routing/sequence/async/{projectId}/jobs/{jobId}

  • Additional GET endpoint can be used to check the job status after submitting an 'asynchronous' call to handle large computations.

Required headers#

  • x-unl-project-id: Pass the unique Project Id also known as VPM Id under this parameter.
  • x-unl-api-key: Secure key to authorize the access to endpoints.

Request Parameters#

  • Mandatory Body Parameters

    • async: It is a boolean parameter to set whether the request is asynchronous or synchronous. If async is set true then all the computations will be done with asynchronous way and return jobId, status, and message as an object. One can send an additional request to the asynchronous GET endpoint by using jobId and projectId. When the job is completed then this endpoint will return the exact same result compared with the synchronous request result, otherwise, it returns status, jobId, and message with updated state.

    • waypoints: It takes an array of objects of RouteGeohashLocation and RouteCoordinatesLocation

      • RouteGeohashLocation: Use 'geohash' with the type enum and geohash string value as described below.
      {
      "type": "geohash",
      "geohash": "u1ku1ku1k"
      }
      • RouteCoordinatesLocation: Use 'coordinates' with the type enum and latitude, and longitude properties with respective values.
      {
      "type": "coordinates",
      "latitude": 42, // It takes a value between -90 and 90
      "longitude": 5 // It takes a value between -180 and 180
      }
  • Optional Parameters

    • departure: It is the time for the departure. If it is not provided then the current date will be attached as the default departure time. The format of the departure should be yyyy-MM-dd'T'HH:mm:ss or yyyy-MM-dd'T'HH:mm:ssX

      • Example : 2021-07-04T17:00:00+02:00
    • transportMode: It defines transport type for the route between origins and destinations. It takes an array of an enum. The values are car, truck, carHOV, bicycle, pedestrian.

    • avoid: It defines avoidance for the route during the calculation. It consists of an array of bounding box objects. A bounding box object has minLat, minLng, maxLat, and maxLng properties. One can set multiple bounding boxes to be avoided on road.

      • Example : avoid: [{maxLat: number, minLat: number, maxLng: number, minLng: number}]
    • routeMode: It takes an enum and values are fastest or shortest. It basically determines how the route will be calculated based on live traffic information, minimum time travel, or minimum distance to reach the destination point.

  • Sample Request Body
{
"async": false,
"waypoints": [
{
"type": "geohash",
"geohash": "u33dbwkjm"
},
{
"type": "geohash",
"geohash": "u33dbwrrb"
},
{
"type": "geohash",
"geohash": "u33dbwq5y"
}
],
"departure": "2022-02-17T06:18:07.291Z",
"transportMode": "pedestrian",
"routeMode": "fastest"
}

Response Parameters#

  • description: It represents a description of the response. It basically gives information about traffic and optimization based on the target.

  • distance: It specifies the total distance between terminal points.

  • time: It specifies the total elapsed time between terminal points.

  • waypoints: It defines an array of objects which have location, estimatedArrival, estimatedDeparture, from, to, distance, and time properties.

    • location: It represents each waypoint as geohash on the map. It is simply a point on the map.

    • estimatedArrival: It specifies the estimated arrival time from one waypoint to the finish waypoint. In this case, the current location has no way to reach directly to end point without passing other waypoints so the value is null.

    • estimatedDeparture: It is the time that defines the estimated departure time from one waypoint to another waypoint.

    • from: It specifies the indicator of the current location whether it is a start or an intermediate point. If it is an intermediate point then it will be shown as a sequence of destination.

    • to: It specifies the indicator of the current location whether it is an intermediate or an end point. If it is an intermediate point then it will be shown as a sequence of destination.

    • distance: It represents the total distance between from and to waypoints in meters.

    • time: It represents the total elapsed time between from and to waypoints in seconds.

  • Sample Response

    {
    "description": "Targeted best time; without traffic",
    "distance": 541,
    "time": 551,
    "waypoints": [
    {
    "location": "u33dbwkjmebj",
    "estimatedArrival": null,
    "estimatedDeparture": "2022-02-17T06:18:07Z",
    "from": "start",
    "to": "destination1",
    "distance": 292,
    "time": 293
    },
    {
    "location": "u33dbwrrbkpd",
    "estimatedArrival": null,
    "estimatedDeparture": "2022-02-17T06:23:00Z",
    "from": "destination1",
    "to": "end",
    "distance": 249,
    "time": 258
    },
    {
    "location": "u33dbwq5ykp8",
    "estimatedArrival": "2022-02-17T06:27:18Z",
    "estimatedDeparture": null,
    "from": "end",
    "to": "end",
    "distance": 0,
    "time": 0
    }
    ]
    }

API Response Code

200 : HTTP ok - Request was successfully processed

201 : HTTP created - Bulk job successfully created

401 : HTTP unauthorized - User does not have permission to carry out this action