Distance Matrix

The Distance Matrix API calculates travel time and distances between origin-destination pairs. UNL distance routing api can calculate upto 10,000 origins and 10,000 destinations. The API supports both asynchronous and synchronous requests to handle long-running requests as a background task.

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

  • There is a limit to use API with synchronous requests with max. cap of 15x100 or 100x1 matrix dimensions.

  • To enable custom options and dynamic traffic, the origins and destinations should be confined to a specific region, defined in the matrix request.

Endpoints#

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

GET https://api.unl.global/v1/routing/matrix/jobs/{jobId}

  • Additional GET endpoint can be used to check the job status after submitting an 'asynchronous' call to handle large computations, limited to 10K X 10K dimensions

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.

  • origins: 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
    }
  • destinations: It is an array of objects of RouteGeohashLocation and RouteCoordinatesLocation. These object types are defined as above.

  • Optional Parameters

    • region: This parameter can be used to define the region for calculation, it can take one of three enum values world, boundingBox, and polygon. The default value is the world. If the special variant world is set in the request body, API enables the calculation of matrix with routes of arbitrary length. The region can also be specified with a bounding box region and defined polygon.
      • Example
        region: {
        "type": "world" // world, boundingBox or polygon
        }
        //The feature polygon can be defined as below
        {
        "type": 'Feature',
        "properties": {}, // The properties is an javascript object and it can be eveything related to specific information. It is like a metadata for the polygon.
        "geometry": {
        "type": 'Polygon',
        "coordinates": [
        [
        [ -5, 52 ],
        [ -4, 56 ],
        [ -2, 51 ],
        [ -7, 54 ],
        [ -5, 52 ]
        ]
        ]
        }
        }
  • departureTime: It is the time of departure at all origins or destinations, in ISO 8601 (RFC 3339). Time zone offset is required to send a correct request to our server.
  • transportMode: It defines transport type for the route between origins and destinations. It takes an array of an enum. The values are car, truck, motorcycle, and pedestrian.
  • avoid: It is an object and defines route avoidance during matrix route calculation. It has two properties to be set which are features and areas. While the features have predefined array of enum values such as tollRoad, controlledAccessHighway, ferry, tunnel, dirtRoad, the areas take maxLat, minLat, maxLng, minLng properties to specify bounding box region.
    • Example
      "avoid": {
      "features": [string], // tollRoad, controlledAccessHighway, ferry, tunnel, dirtRoad
      "areas": {minLat: number, maxLat: number, minLng: number, maxLng: number}
      }
  • Sample Request Body
{
"async": false,
"origins": [
{
"type": "geohash",
"geohash": "u1ku1ku1k"
},
{
"type": "geohash",
"geohash": "u1ku1ku2k"
}
],
"destinations": [
{
"type": "geohash",
"geohash": "u1ku2ku1k"
},
{
"type": "geohash",
"geohash": "u1ku2ku2k"
}
],
"transportMode": "car",
"region": {
"type": "world"
},
"avoid": {
"features": ["tollRoad"]
}
}

Response Parameters#

  • origins: It specifies origins as an array of geohash. These origins are coming from requests and placed into the response to be used again.

  • destinations: It specifies destination as an array of geohash. These destinations are coming from requests and placed into the response to be used again.

  • distances: It represents the distance calculated by the API between the origin and destination pairs. The response is structured as a nested array of each origin to all destination distances. For example, consider request contains two elements of origins and destinations each. In this case, the first row will contain the distance between the first point in the origin array and all destinations, the second row will be the distance between the second point in the origins array and all destinations. All the values will be presented in meters.

  • times: It defines a nested array in order to show the time being passed between every combination of the origins and destinations in the request. All the values will be presented in seconds. The array is structured similar to the structure of distances array.
  • Samples Response

    {
    "origins": [
    "u1ku1ku1k",
    "u1ku1ku2k"
    ],
    "destinations": [
    "u1ku2ku1k",
    "u1ku2ku2k"
    ],
    "distances": [
    [
    8682,
    8686
    ],
    [
    8682,
    8686
    ]
    ],
    "times": [
    [
    635,
    635
    ],
    [
    635,
    635
    ]
    ],
    "region": {
    "type": "world"
    }
    }

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