Route Matching

The Route Matching API is used to match GPS drive traces onto the most likely drivable route on the map and getting more accurate arrival time estimation via ETA tracking and toll avoidance option.

  • Base URI: https://api.unl.global/{version}

  • The API considers real-time and historical traffic information in its calculations by default. One can override it by setting traffic parameter as disabled

  • The current version of the API services is v1

Endpoints#

POST https://api.unl.global/v1/routing/matchroute

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

    • 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
    • arrival: It is the same as the departure parameter but it specifies the arrival time for the destination when started to journey. Note that when the arrival parameter is specified in the request body then toll cost is not considered anymore.
    • 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.
    • traffic: It specifies if live traffic information is included during the route calculation or not. It takes two values which are enabled and disabled respectively. By default, traffic property is set enabled. Sample Request Body
{
"waypoints": [
{
"type": "geohash",
"geohash": "u33dbwkjm"
},
{
"type": "geohash",
"geohash": "u33dbwrrb"
},
{
"type": "geohash",
"geohash": "u33dbwq5y"
}
],
"departure": "2022-03-01T08:37:41.660Z",
"transportMode": "car",
"routeMode": "fastest",
"traffic": "enabled"
}

Response Parameters#

  • overview: A single GeoJSON object that specifies route geometry and main properties of the route between each waypoint.

  • linestring: It defines the total route in the form of geohash array. Each element represents a point on the map. The linestring can be visualized easily on the map via some drawing tool.

  • length: It specifies the total distance between terminal points. It is defined in meters.

  • duration: It specifies the total elapsed time between terminal points. It is defined in seconds.

  • 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. Currently, API supports only fastest mode.

  • transportMode: It specifies the transport mode information coming from the request body.

  • traffic: It specifies if the traffic information is enabled or disabled.

  • segments: It defines an array of objects which have from, to, distance, and time properties.

    • from: It specifies the indicator of the current location whether it is a start, end, or intermediate point. If it is an intermediate point then it will be shown as a destination with the number suffix such as destination1 means it is the first destination coming right after starting point.

    • to: It specifies the indicator of the current location whether it is an end or intermediate point. If it is an intermediate point then it will be shown as a destination with the number suffix such as destination1 means it is the first destination coming right after the intermediate point.

    • distance: It defines the total distance between waypoints starting from the current location to the next destination. It is a number presented meters.

    • time: It defines the total elapsed time between waypoints starting from the current location to the next destination. It is a number presented seconds.

  • Samples Response
{
"overview": {
"linestring": [
"swefsp2gw5fg",
"swefsp2gw5fg",
"swefsp36gr7f",
"swefsp3dfjkp",
"swefsp3dfjkp",
"swefsp3d1pn7",
"swefsp3d1pn7",
"swefsp1ry4tm",
"swefsp1rttn6",
"swefsp1rttn6",
"swefsp1qeee2",
"swefsp1q6sj6",
"swefsp1q6sj6",
"swefsp1jxvsn",
"swefsp1jm4d8",
"swefsp1jm4d8",
"swefsp0utqh2",
"swefsp0utqh2",
"swefsp0ueb2m",
"swefsp0ueb2m"
],
"length": 238,
"duration": 21
},
"segments": [
{
"from": "swefsp2unmzt",
"to": "swefsp3d4n8r",
"distance": 91,
"time": 8
},
{
"from": "swefsp3d4n8r",
"to": "swefsp1rgdcg",
"distance": 51,
"time": 5
},
{
"from": "swefsp1rgdcg",
"to": "swefsp1q5x1c",
"distance": 27,
"time": 2
},
{
"from": "swefsp1q5x1c",
"to": "swefsp0ucgj3",
"distance": 68,
"time": 6
}
],
"routeMode": "fastest",
"transportMode": "car",
"traffic": "enabled"
}

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