> For the complete documentation index, see [llms.txt](https://docs.distance.tools/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.distance.tools/tools/api/api-reference/distance-route.md).

# distance/route

{% openapi src="<https://raw.githubusercontent.com/StephanGeorg/distance.tools-public-docs/main/api/openapi.yaml>" path="/distance/route" method="post" %}
<https://raw.githubusercontent.com/StephanGeorg/distance.tools-public-docs/main/api/openapi.yaml>
{% endopenapi %}

### **Request Body**

The `route` object defines a route with all its waypoints and has a minimum of two [waypoints](#waypoint) and a maximum of **75** [waypoints](#waypoint).

```json
{
  "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 href="#waypoint" id="waypoint"></a>

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.

```json
{
    "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](/features/input-data.md).

***

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

```json
{
  "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 <a href="#route" id="route"></a>

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**

```json
{
  "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](/features/calculation.md).

**Car routing distance**

```json
{
  "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](/features/input-data.md) a **`404`** is returned. [Learn more about response statuses](/tools/api/api-reference.md#status-codes).

#### &#x20; <a href="#distance-route-detailed" id="distance-route-detailed"></a>