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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.distance.tools/tools/api/api-reference/distance-route.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.