# Routing

> Calculate a route between an origin and a destination for a generic vehicle or a pedestrian, based on the HERE Routing API v8.

To see the full list of parameters or their details, visit the [HERE Routing API documentation](https://docs.here.com/routing/reference/routing-api-v8-calculateroutespost).

## Endpoint

`POST https://{host}:{port}/EgonMbk/api/routes`

Replace `{host}` and `{port}` with the address of your Egon instance.

## Headers

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `token` | String | Yes | Authentication token sent in the `token` request header. |

## Request

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `transportMode` | String | Yes | Mode of transport: `car`, `truck`, `pedestrian`, `bicycle`, `scooter`, `taxi`, `bus`, `privateBus`, or `networkRestrictedTruck`. Default value: `car` |
| `origin` | String | Yes | Origin waypoint (WGS84). Format: `{lat},{lng}`. |
| `destination` | String | Yes | Destination waypoint (WGS84). Format: `{lat},{lng}`. |
| `via` | String | No | Via waypoint(s). Multiple values are allowed and are traversed sequentially in the specified order. |
| `routingMode` | String | No | Route optimization: `fast` (default) or `short`. Default value: `fast` |
| `return` | String | No | Attributes to include in the response, including `polyline`, `actions`, `instructions`, `summary`, `travelSummary`, `turnByTurnActions`, `elevation`, `routeHandle`, `incidents`, and `tolls`. |
| `spans` | String | No | Map content attributes to include per span. Requires `return=polyline`. |
| `units` | String | No | Units of measurement: `metric` (default) or `imperial`. Default value: `metric` |
| `lang` | String | No | Preferred response language in BCP 47 format, for example `it,en-US`. |

### Example request

```bash
curl -X POST "https://{host}:{port}/EgonMbk/api/routes?transportMode=car&origin=44.9741733,7.7232365&destination=43.87644,11.11885&routingMode=fast&units=metric" \
  -H "token: YOUR_API_KEY"
```

## Response

Calculated routes and system status.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | Object | No | Calculated route data. |
| `data.routes` | Array | No | Route(s) calculated. |
| `data.routes.id` | String | No | Unique route id. |
| `data.routes.sections` | Array | No | Sections composing the route. |
| `data.routes.sections.id` | String | No | Section id. |
| `data.routes.sections.type` | String | No | Section type: `vehicle`, `pedestrian`, or `transit`. |
| `data.routes.sections.departure` | Object | No |  |
| `data.routes.sections.departure.place` | Object | No |  |
| `data.routes.sections.departure.place.type` | String | No | Type of place. |
| `data.routes.sections.departure.place.location` | Object | No |  |
| `data.routes.sections.departure.place.location.lat` | Number | No | Latitude (WGS84). |
| `data.routes.sections.departure.place.location.lng` | Number | No | Longitude (WGS84). |
| `data.routes.sections.departure.place.originalLocation` | Object | No |  |
| `data.routes.sections.departure.place.originalLocation.lat` | Number | No | Latitude (WGS84). |
| `data.routes.sections.departure.place.originalLocation.lng` | Number | No | Longitude (WGS84). |
| `data.routes.sections.arrival` | Object | No |  |
| `data.routes.sections.arrival.place` | Object | No |  |
| `data.routes.sections.arrival.place.type` | String | No | Type of place. |
| `data.routes.sections.arrival.place.location` | Object | No |  |
| `data.routes.sections.arrival.place.location.lat` | Number | No | Latitude (WGS84). |
| `data.routes.sections.arrival.place.location.lng` | Number | No | Longitude (WGS84). |
| `data.routes.sections.arrival.place.originalLocation` | Object | No |  |
| `data.routes.sections.arrival.place.originalLocation.lat` | Number | No | Latitude (WGS84). |
| `data.routes.sections.arrival.place.originalLocation.lng` | Number | No | Longitude (WGS84). |
| `data.routes.sections.summary` | Object | No |  |
| `data.routes.sections.summary.duration` | Number | No | Duration in seconds. |
| `data.routes.sections.summary.length` | Number | No | Length in meters. |
| `data.routes.sections.summary.baseDuration` | Number | No | Duration ignoring traffic conditions. |
| `data.routes.sections.transport` | Object | No |  |
| `data.routes.sections.transport.mode` | String | No | Mode of transport used. |
| `data.routes.sections.polyline` | String | No | Route geometry in Flexible Polyline encoding. |
| `data.routes.sections.actions` | Array | No | Actions required to complete the section. |
| `data.routes.sections.spans` | Array | No | Map content attributes for each span. |
| `data.routes.routeLabels` | Array of String | No | Most important names and route numbers. |
| `data.routes.routeHandle` | String | No | Encoded route handle for later route decoding. |
| `data.notices` | Array | No | Issues related to the route calculation. |
| `system` | Object | No | System error status. |
| `system.ret_code` | Number | No | Code: `0` means no blocking error; a value different from `0` is a blocking error code. |
| `system.des_ret_code` | String | No | Description of the return status. |

### Example responses

**HTTP 200: Valid response**

Route successfully calculated between origin and destination.

```json
{
  "data": {
    "routes": [
      {
        "id": "8806be89-f32f-4dab-a794-5717c6e2720d",
        "sections": [
          {
            "id": "9f11b95c-d189-4d58-8701-f70a245ca6da",
            "type": "vehicle",
            "departure": {
              "place": {
                "type": "place",
                "location": {
                  "lat": 44.9741733,
                  "lng": 7.7232365
                },
                "originalLocation": {
                  "lat": 44.9741733,
                  "lng": 7.7232365
                }
              }
            },
            "arrival": {
              "place": {
                "type": "place",
                "location": {
                  "lat": 43.87644,
                  "lng": 11.11885
                },
                "originalLocation": {
                  "lat": 43.87644,
                  "lng": 11.11885
                }
              }
            },
            "transport": {
              "mode": "car"
            }
          }
        ]
      }
    ]
  },
  "system": {
    "retCode": 0,
    "desRetCode": "Ok"
  }
}
```

**HTTP 200: Missing parameters**

Parameters are missing.

```json
{
  "system": {
    "ret_code": 1,
    "des_ret_code": "Invalid request"
  }
}
```

**HTTP 200: Incomplete parameters**

Parameters are incomplete.

```json
{
  "system": {
    "ret_code": 1,
    "des_ret_code": "Malformed request"
  }
}
```

**HTTP 200: Missing token**

Provide the required authentication token in the token request header.

```json
{
  "system": {
    "ret_code": 1,
    "des_ret_code": "token not found"
  }
}
```

**HTTP 200: Invalid token**

The supplied token is invalid, expired, or not authorized for this service.

```json
{
  "system": {
    "ret_code": 1,
    "des_ret_code": "token not valid"
  }
}
```