Skip to main content

Distance / Route API

Compute optimal driving, trucking, and walking routes with turn-by-turn guidance, live traffic awareness, and multi-stop sequencing.

Overview & Solution​

Transportation and field travel costs constitute a major expense in logistics, supply chains, and mobile operations. The Distance / Route API calculates accurate driving distances, realistic transit durations, and turn-by-turn navigation paths based on rich topological road networks and real-time traffic conditions.

Industry Use Cases​

1. Supply Chain & Long-Haul Trucking​

  • Toll & Fuel Optimization: Compare toll vs. non-toll highway alternatives to optimize transport budgets.

2. Quick-Commerce & Food Delivery​

  • Accurate ETAs: Provide customers with realistic arrival predictions updated continuously according to traffic congestion.
  • Rider Navigation: Turn-by-turn polylines and voice-guidance data for mobile navigation apps.

3. Field Service Dispatch​

  • Multi-Stop Journey Planning: Sequence maintenance service tickets in the most efficient order to minimize daily fuel consumption and windshield time.

The Sovereign Routing Advantage​

  • Turn-by-Turn Maneuvers: Delivers detailed instructions (turn left, merge, exit roundabout) with lane guidance.
  • Custom Costing Models: Supports car, heavy truck, two-wheeler, and pedestrian profiles.

API reference​

note

This page covers two related endpoints. Route returns the travelable path, instructions and geometry; Distance returns distance and duration only.

Route API​

Master list reference: #3a

Route and Journey Intelligence APIs · API key only

Returns the travelable path between two or more stops, in the order given: geometry, turn-by-turn instructions, and time and length per leg.

Endpoints​

All requests need only your API key, as the api-key query parameter - no bearer token:

?api-key=<apiKey>
Get the drivable path between waypoints​
POST /routing/adapter/route

Base URL: https://api-gw.sovereignsolutions.com/gateway

Request Parameters

ParameterInTypeRequiredDescriptionExample
locationsbodyarrayNoStops, visited in the order given. At least two.
locations[]bodyobjectNo
locations[].latbodynumberNoLatitude of the point, decimal degrees.
locations[].lonbodynumberNoLongitude of the point, decimal degrees.
costingbodystringNoTravel mode used for costing. The examples use auto (driving) and pedestrian (walking).
unitsbodystringNoDistance unit: km.

Request body

{
  "locations": [
    {
      "lat": 21.4943067,
      "lon": 86.8692782
    },
    {
      "lat": 21.4335349694959,
      "lon": 86.8405786566617
    }
  ],
  "costing": "auto",
  "units": "km"
}

Response Schema

200 OK

{
  "trip": {
    "locations": [
      {
        "type": "break",
        "lat": 21.494306,
        "lon": 86.869278,
        "side_of_street": "left",
        "original_index": 0
      },
      {
        "type": "break",
        "lat": 21.433534,
        "lon": 86.840578,
        "side_of_street": "left",
        "original_index": 1
      }
    ],
    "legs": [
      {
        "maneuvers": [
          {
            "type": 3,
            "instruction": "Drive east.",
            "verbal_succinct_transition_instruction": "Drive east.",
            "verbal_pre_transition_instruction": "Drive east.",
            "verbal_post_transition_instruction": "Continue for 2 kilometers.",
            "time": 158.239,
            "length": 2.197,
            "cost": 151.988,
            "begin_shape_index": 0,
            "end_shape_index": 28,
            "travel_mode": "drive",
            "travel_type": "car"
          },
          {
            "type": 10,
            "instruction": "Turn right onto NH16/AH45/Balasore Bypass. Continue on NH16/AH45.",
            "verbal_transition_alert_instruction": "Turn right onto NH16.",
            "verbal_succinct_transition_instruction": "Turn right.",
            "verbal_pre_transition_instruction": "Turn right onto NH16, AH45.",
            "verbal_post_transition_instruction": "Continue on NH16, AH45 for 9 kilometers.",
            "street_names": [
              "NH16",
              "AH45"
            ],
            "begin_street_names": [
              "NH16",
              "AH45",
              "Balasore Bypass"
            ],
            "time": 365.522,
            "length": 8.966,
            "cost": 340.377,
            "begin_shape_index": 28,
            "end_shape_index": 76,
            "travel_mode": "drive",
            "travel_type": "car"
          }
        ],
        "summary": {
          "has_time_restrictions": false,
          "has_toll": false,
          "has_highway": false,
          "has_ferry": false,
          "min_lat": 21.431431,
          "min_lon": 86.838567,
          "max_lat": 21.49335,
          "max_lon": 86.889226,
          "time": 547.566,
          "length": 11.486,
          "cost": 521.159
        },
        "shape": "}wu~g@si`udD|AkPhBgm@aDoYo@eLc@sfFp@oJpHc_@lFiYxHm`A~@aMsAkPuWax@{DwQoBmSUkSdAoeFsAaUyFk[aNal@_FeO}DeWkFaU{x@guBwGiYaSgjB]_IY_H]kG`WhCx_ArJr~Dd`@tt@hHvcArLjkAtNfMrAr`AnKpmAfObgBfSzaCnXbg@lJje@jPftCfmArmDl{Avf@hTbe@`QxUxInkAhf@jkE`lB`VlKxP`ItUvNzTtSl[b]hgFr_HnyApiBf}E|gGtpA||AtsAdfBn{@`gA`UpZpo@tx@p{@`kAvm@zw@zgC`dDveIp|JrfEdiFpv@x`A|rArbBrnAz{ArCjDhxAvjBli@nq@pK`Oz\\~a@ftAdcB~AxByHzGunBefC"
      }
    ],
    "summary": {
      "has_time_restrictions": false,
      "has_toll": false,
      "has_highway": false,
      "has_ferry": false,
      "min_lat": 21.431431,
      "min_lon": 86.838567,
      "max_lat": 21.49335,
      "max_lon": 86.889226,
      "time": 547.566,
      "length": 11.486,
      "cost": 521.159
    },
    "status_message": "Found route between points",
    "status": 0,
    "units": "kilometers",
    "language": "en-US"
  }
}
FieldTypeDescription
tripobject
trip.locationsarrayThe input stops as snapped to the road network.
trip.locations[]object
trip.locations[].typestring
trip.locations[].latnumber
trip.locations[].lonnumber
trip.locations[].side_of_streetstringSide of the street the stop is on.
trip.locations[].original_indexintegerPosition of this stop in your request.
trip.legsarrayOne leg between each pair of consecutive stops.
trip.legs[]object
trip.legs[].maneuversarrayTurn-by-turn instructions for the leg.
trip.legs[].maneuvers[]object
trip.legs[].maneuvers[].typeinteger
trip.legs[].maneuvers[].instructionstringHuman-readable instruction.
trip.legs[].maneuvers[].verbal_succinct_transition_instructionstring
trip.legs[].maneuvers[].verbal_pre_transition_instructionstring
trip.legs[].maneuvers[].verbal_post_transition_instructionstring
trip.legs[].maneuvers[].timenumberTime for this maneuver, seconds.
trip.legs[].maneuvers[].lengthnumberLength of this maneuver, in units.
trip.legs[].maneuvers[].costnumber
trip.legs[].maneuvers[].begin_shape_indexinteger
trip.legs[].maneuvers[].end_shape_indexinteger
trip.legs[].maneuvers[].travel_modestring
trip.legs[].maneuvers[].travel_typestring
trip.legs[].summaryobject
trip.legs[].summary.has_time_restrictionsboolean
trip.legs[].summary.has_tollboolean
trip.legs[].summary.has_highwayboolean
trip.legs[].summary.has_ferryboolean
trip.legs[].summary.min_latnumber
trip.legs[].summary.min_lonnumber
trip.legs[].summary.max_latnumber
trip.legs[].summary.max_lonnumber
trip.legs[].summary.timenumberLeg travel time, seconds.
trip.legs[].summary.lengthnumberLeg length, in units.
trip.legs[].summary.costnumber
trip.legs[].shapestringLeg geometry as an encoded polyline.
trip.summaryobject
trip.summary.has_time_restrictionsboolean
trip.summary.has_tollbooleantrue when the route uses a toll road.
trip.summary.has_highwaybooleantrue when the route uses a highway.
trip.summary.has_ferrybooleantrue when the route uses a ferry.
trip.summary.min_latnumber
trip.summary.min_lonnumber
trip.summary.max_latnumber
trip.summary.max_lonnumber
trip.summary.timenumberTotal travel time, seconds.
trip.summary.lengthnumberTotal length, in units.
trip.summary.costnumber
trip.status_messagestringResult message.
trip.statusinteger0 when a route was found.
trip.unitsstringDistance unit used in the response.
trip.languagestringLanguage of the instructions.

Example​

curl -X POST 'https://api-gw.sovereignsolutions.com/gateway/routing/adapter/route?api-key=$API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"locations": [{"lat": 21.4943067, "lon": 86.8692782}, {"lat": 21.4335349694959, "lon": 86.8405786566617}], "costing": "auto", "units": "km"}'

See also​

Distance API​

Master list reference: #3b

Route and Journey Intelligence APIs · API key only

Returns distance (metres) and estimated duration (seconds) between waypoints. Lighter than the Route API when you only need the numbers.

Endpoints​

MethodPathPurpose
GET/routing/in-shortest/route/v1/{profile}/{coordinates}Distance API - two points
GET/routing/in-shortest/route/v1/{profile}/{coordinates}Distance API - multiple points

All requests need only your API key, as the api-key query parameter - no bearer token:

?api-key=<apiKey>
Distance API - two points​
GET /routing/in-shortest/route/v1/{profile}/{coordinates}

Base URL: https://api-gw.sovereignsolutions.com/gateway

Request Parameters

ParameterInTypeRequiredDescriptionExample
profilepathstringYesRouting profile. The examples use car and foot.car
coordinatespathstringYesSemicolon-separated lon,lat pairs. Two pairs = point-to-point; more than two = one leg per consecutive pair.86.8692782,21.4943067;86.8405786566617,21.4335349694959

Response Schema

200 OK

{
  "routes": [
    {
      "weight_name": "taxi",
      "weight": 11486.098,
      "duration": 547.567,
      "distance": 11486.098,
      "legs": [
        {
          "weight": 11486.098,
          "duration": 547.567,
          "steps": [],
          "distance": 11486.098,
          "summary": ""
        }
      ],
      "geometry": "indbCapeqOHw@HsCOsACi@CeVBc@^gBVsA\\oEFm@Iw@mAuDS{@IaAA_ADaVGgAWyAq@oCUs@QmAWeAyDyJ[sA_AwIA_@C[A[jALnEd@dRhBjD\\zEj@rFp@l@FpEf@xFr@lI~@`LpA`Cb@xBv@|MxFlPfH~BbAxBx@fAb@tF|BlSzIhAf@v@^fAp@dA`AzA`BfVx[~GtIfUnYdGjHlGhI`EdFdAxAzCvD`ErFtCtDtLnOt_@be@|RlVpDpEjG~H|FfHNP|GvIfC`Df@r@~AnBnG~HHJ_@ZeJoL"
    }
  ],
  "waypoints": [
    {
      "distance": 364.278,
      "name": "",
      "location": [
        86.86865,
        21.491087
      ]
    },
    {
      "distance": 23.635,
      "name": "NH16",
      "location": [
        86.84073,
        21.433376
      ]
    }
  ],
  "code": "Ok"
}
FieldTypeDescription
routesarrayThe route found.
routes[]object
routes[].weight_namestringName of the cost model used.
routes[].weightnumberInternal routing cost. Ignore it.
routes[].durationnumberTotal duration, seconds.
routes[].distancenumberTotal distance, metres.
routes[].legsarrayOne leg between each pair of consecutive points.
routes[].legs[]object
routes[].legs[].weightnumber
routes[].legs[].durationnumberLeg duration, seconds.
routes[].legs[].stepsarray
routes[].legs[].distancenumberLeg distance, metres.
routes[].legs[].summarystring
routes[].geometrystringRoute geometry as an encoded polyline.
waypointsarrayInput points snapped to the road network, in input order.
waypoints[]object
waypoints[].distancenumberDistance from the input point to the snapped position, metres.
waypoints[].namestringRoad name at the snapped position.
waypoints[].locationarraySnapped position, [longitude, latitude].
waypoints[].location[]number
codestringOk on success.
Distance API - multiple points​
GET /routing/in-shortest/route/v1/{profile}/{coordinates}

Base URL: https://api-gw.sovereignsolutions.com/gateway

Request Parameters

ParameterInTypeRequiredDescriptionExample
profilepathstringYesRouting profile. The examples use car and foot.foot
coordinatespathstringYesSemicolon-separated lon,lat pairs. Two pairs = point-to-point; more than two = one leg per consecutive pair.80.267284,13.0363036;80.267779,13.034928;80.267437,13.03525;80.267291,13.036289;80.251724,13.032119

Response Schema

200 OK

{
  "routes": [
    {
      "weight_name": "pedestrian",
      "weight": 2360.007,
      "duration": 1668.887,
      "distance": 2360.007,
      "legs": [
        {
          "weight": 152.966,
          "duration": 107.976,
          "steps": [],
          "distance": 152.966,
          "summary": ""
        },
        {
          "weight": 107.549,
          "duration": 75.917,
          "steps": [],
          "distance": 107.549,
          "summary": ""
        }
      ],
      "geometry": "qaqnA}f|hNCEISIURCx@Ib@ChBOiBNHHt@n@u@o@IIc@By@HSBHTHRBDBFHJx@f@`Al@vAfANXp@tAZdBT|@x@jBPT`AtALLz@lA?pHDjADjDApA?RCDEHSl@GJBRGv@Ef@ABEdA@XAdAFvAB~@?\\?lAAvAAHElBI|AMjEChCIbDNJbB`AnA|@B@LHMpDtA@"
    }
  ],
  "waypoints": [
    {
      "distance": 48.114,
      "name": "Subbarayan Salai",
      "location": [
        80.267512,
        13.035933
      ]
    },
    {
      "distance": 15.645,
      "name": "RK Mutt Road",
      "location": [
        80.267922,
        13.034948
      ]
    }
  ],
  "code": "Ok"
}
FieldTypeDescription
routesarrayThe route found.
routes[]object
routes[].weight_namestringName of the cost model used.
routes[].weightnumberInternal routing cost. Ignore it.
routes[].durationnumberTotal duration, seconds.
routes[].distancenumberTotal distance, metres.
routes[].legsarrayOne leg between each pair of consecutive points.
routes[].legs[]object
routes[].legs[].weightnumber
routes[].legs[].durationnumberLeg duration, seconds.
routes[].legs[].stepsarray
routes[].legs[].distancenumberLeg distance, metres.
routes[].legs[].summarystring
routes[].geometrystringRoute geometry as an encoded polyline.
waypointsarrayInput points snapped to the road network, in input order.
waypoints[]object
waypoints[].distancenumberDistance from the input point to the snapped position, metres.
waypoints[].namestringRoad name at the snapped position.
waypoints[].locationarraySnapped position, [longitude, latitude].
waypoints[].location[]number
codestringOk on success.

Returns one leg per consecutive pair of points. The example response is shortened to the first two legs and waypoints.

Example​

curl -X GET 'https://api-gw.sovereignsolutions.com/gateway/routing/in-shortest/route/v1/car/86.8692782,21.4943067;86.8405786566617,21.4335349694959?api-key=$API_KEY'
ISO 27001:2022 Certified – Information Security Management SystemSovereign Solutions is ISO 27001:2022 certified for Information Security Management