Response

Information about response payload, units and additional information

Status codes

Code	Description
200	Valid request and all waypoints could be geocoded.
400	Invalid request with information about validation.
404	Valid request but not all waypoints could be geocoded.
429	Load balancer rejected the request because too many request in parallel or your usage limits exceeded.

You'll get a HTTP status code 200 with waypoint information even if there could no car routing distance found. If one of the waypoints could not be found and geocoded a 404 is returned.

Units

All distances are given in kilometers. To convert distances into miles, they must be multiplied by 0.621371. Maritime distances are also given in nautical miles.

The travel duration for car routing is given in seconds. For maritime routes, which are given in hours duration is calculated with a speed of 20 knots. 20 knots = 20 NM / hour.

Result

A DistanceAPI result consists of 3 main parts. route contains summarized info about route between all waypoints. points array contains additional information about the waypoints of the requested route. steps array describes distance, duration and travel information for the ways between each waypoints.

{
  "route": { ... }, // Contains summarized info about route between all waypoints
  "points": [...],  // Contains geocoding & geographical information of waypoints
  "steps": [...]    // Contains routing information of each step of a route
}

Route

The route object contains summarized information about the route between all waypoints. This object is available in responses from all endpoints returning route information.

Airline distance

{
  "route": {
    "vincenty": 709.63,                // airline distance in Kilometer 
    "haversine": 708.6068727785872,    // airline distance in Kilometer
    "greatCircle": 708.6068950233187,  // airline distance in Kilometer  
  }
}

Learn more about airline distance calculation.

Car routing distance

{
  "route": {
    "car": {
      "distance": 812.1059,  // car routing distance in Kilometer
      "duration": 39012.7,   // car routing duration in Seconds
      "status": "found"      // Status weather a round was "found" or "not found"
    }
  }
}

You'll get a HTTP status code 200 with waypoint information even if there could no car routing distance found. status flag indicates a car route was found or not found. If one of the waypoints could not be found and geocoded a 404 is returned. Learn more about response statuses.

Car routing detailed

If you use the distance/route/detailed endpoint additional information is returned in the car response object.

{
  "route": {
    "car": {
      "distance": 812.1059,  // car routing distance in Kilometer
      "duration": 39012.7,   // car routing duration in Seconds
      "status": "found",     // Status weather a route was "found" or "not found"
      "midpoint": {	     // Midpoint of the car route as coordinates and distance				
	"distance": 406.05295,
	"coordinates": [9.71657787483215,56.72328303201471]
      },
      "countries": [{        	  // Breakdown of route by country 		
	"country": "NO",	  // Country code (ISO 3166-1 alpha-2)			
	"distance": 169.16165897, // Distance in Kilometer of car route in country 
	"duration": 8126.34541    // Duration in Seconds of car route in country 
      }, {
	"country": "DK",
	"distance": 379.65950825,
	"duration": 18238.43725
      }, {
	"country": "DE",
	"distance": 157.87338696,
	"duration": 7584.0688799
      }]
    }
  }
}

Maritime distances

Maritime distances are returned as kilometers and nautical miles. The duration is calculated with a speed of 20 knots. 20 knots = 20 NM / hour.

{
  "route": {
    "sea": {
      "distance": 960.2291039330195,    // maritime distance in Kilometer
      "distanceNM": 518.4824262723614,  // maritime distance in Nautical miles
      "duration": 25.92412131361807,    // travel time in hours
      "status": "found"                 // flag indicating a maritime was found 
    }
  }  
}

You'll get a HTTP status code 200 with waypoint information even if there could no car routing distance found. status flag indicates a maritime route was found or not found. If one of the waypoints could not be found and geocoded a 404 is returned. Learn more about response statuses.

Steps

Points