distance/route

Calculate distance (airline, car routing) between points

Car routing and airline distance

post

Calculate airline and car routing distances between multiple points.

Authorizations

XBillingToken

X-Billing-TokenstringRequired

Authentication token for billing. Get your token at https://developers.distance.tools.

Query parameters

carbooleanOptional

Get car routing distances

flightbooleanOptional

Get flight distances

equalbooleanOptional

Get equal distances

Body

application/json

Responses

200

Valid request and found waypoints

application/json

stepsobject[]Optional

Routing steps

pointsobject[]Optional

Routing points

400

Bad Request - Invalid request

404

Not Found - Valid request but waypoints not found

post

/distance/route

HTTPcURLJavaScriptPython

POST /api/v2/distance/route HTTP/1.1
Host: api.distance.tools
X-Billing-Token: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 44

{
  "route": [
    {
      "name": "text",
      "country": "text"
    }
  ]
}

{
  "route": {
    "vincenty": 1,
    "haversine": 1,
    "greatCircle": 1,
    "car": {
      "distance": 1,
      "duration": 1,
      "status": "text"
    }
  },
  "steps": [
    {}
  ],
  "points": [
    {}
  ]
}

Request Body

The route object defines a route with all its waypoints and has a minimum of two waypoints and a maximum of 75 waypoints.

{
  "route": [{
    "name": "Berlin",  // Required: Any input text or lat,lng
    "country": "DEU"   // Optional: ISO 3166-1 alpha-3 country code
  },{
    "name": "Hamburg", // Required: Any input text or lat,lng
    "country": "DEU"   // Optional: ISO 3166-1 alpha-3 country code
  },{
    "name": "52.5162,13.37795"
  },{
    ...
  }]
}

Waypoint

A waypoint describes each step of a route and is defined as its required name field and an optional country field to specify its specific location.

{
    "name": "Berlin",  // Required: Any input text or lat,lng
    "country": "DEU"   // Optional: ISO 3166-1 alpha-3 country code
}

The name field can contain any textual information about the location like postal address, city or region, postal code, IATA code, what3words or a coordinate in the format latitude,longitude. If using coordinate or what3words you do not need to specify the country. Learn more about input and geocoding.

---

Response

A Distance API response 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.