Isoline

The Isoline Routing API calculates traversable region around the origin points based on distance or time constraints. The result of the endpoint will be represented as a polygon where each point can be reached as per the given time or distance constraints.

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

  • The API considers real-time and historical traffic information in its calculations.

  • The current of the API services is v1

  • The service is not available for Japan Region at the moment.

Endpoints#

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

GET https://api.unl.global/v1/routing/isoline/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.

    • 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.

    • range: It is an object that defines route computation based on distance or time. Basically, it has two properties type and value.

      • type : It is enum and accept either distance or time values.
      • value: It is a number that shows the distance in meters and time in seconds.

  • Optional Parameters

    • mode: It is an enum value and takes short and fast. short mode simulates the calculation of minimum route distance disregarding any speed information. fast mode simulates the calculation of minimum travel time from start point to destination

    • transportMode: It defines transport type for the route between origins and destinations. It takes an array of an enum. The values are car, truck, pedestrian.

    • avoid: It is an object and defines route avoidance during the calculation. It has to consist of an array of enum values as tollRoad, controlledAccessHighway, ferry, tunnel, dirtRoad.

    • optimizeFor: It specifies how isoline route calculation is optimized. It takes quality, performance, and balanced values. The default value is balanced.

      • quality: calculation of isoline focuses on quality, that is, the graph used for isoline calculation has higher granularity generating an isoline that is more precise.

      • performance: calculation of isoline is performance-centric, quality of isoline is reduced to provide better performance.

      • balanced: calculation of isoline takes a balanced approach averaging between quality and performance.

    • shape: It defines a number of points in the isoline route shape so that the quality and detail of the calculated region could be either increased or decreased. It takes numbers greater than 30. It is recommended that the shape property value should be either 100 or greater for better visibility.

  • Sample Request Body
{
"async": false,
"origin": {
"type": "geohash",
"geohash": "u33dbwrrr"
},
"range": {
"type": "distance",
"value": 4000
},
"transportMode": "pedestrian",
"mode": "fast",
"shape": 30,
"optimizeFor": "performance",
"avoid": ["tollRoad", "dirtRoad"]
}

Response Parameters#

  • origin: It specifies origin in the form of geohash. Origin is coming from requests and placed into the response to be used again.

  • range: It represents the range paramter used with the request body.

  • mode: It represents the mode paramter used with the request body.

  • transportMode: It represents the transport mode paramter used with the request body.

  • isoline: It represents Polygon feature which consists of an array of coordinates whose starting point and finishing point are the same. The number of polygon is dependent on the number of ranges requested.

  • Sample Response
{
"origin": "u33dbwrrr",
"range": {
"type": "distance",
"value": 4000
},
"routeMode": "fast",
"transportMode": "pedestrian",
"isoline": {
"type": "Feature",
"properties": {},
"geometry": {
"type": "Polygon",
"coordinates": [[...], [...], ...]
}
}
}

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

Edit this page