---
title: Traffic-Aware Routing | Plaza Docs
description: Factor in historical congestion patterns when calculating ETAs and routes.
---

Traffic-Aware Routing extends [Directions](/guides/directions/index.md) with historical congestion data. Specify a departure time and Plaza adjusts route selection and ETAs based on typical traffic patterns for that time of day and day of week.

Traffic-Aware Routing is a [premium endpoint](/guides/authentication#premium-endpoints/index.md) — each request counts as 4x.

## Endpoint

```
POST /api/v1/route
```

Traffic-aware routing uses the same endpoint as standard directions. Include the `depart_at` parameter to activate traffic adjustments.

## Request body

All [standard Directions parameters](/guides/directions/index.md) apply, plus:

| Field           | Type   | Default        | Description                                                          |
| --------------- | ------ | -------------- | -------------------------------------------------------------------- |
| `depart_at`     | string | —              | ISO 8601 departure time (e.g., `"2026-03-23T08:00:00Z"`) or `"now"`. |
| `traffic_model` | string | `"best_guess"` | Prediction model: `best_guess`, `pessimistic`, or `optimistic`.      |

### Traffic models

| Model         | Description                                                             |
| ------------- | ----------------------------------------------------------------------- |
| `best_guess`  | Uses actual historical traffic data for the departure time.             |
| `pessimistic` | Assumes worst-case conditions — caps speed factors at 0.7.              |
| `optimistic`  | Assumes best-case conditions — floors speed factors at 1.0 (free-flow). |

## Basic request

Terminal window

```
curl -X POST https://plaza.fyi/api/v1/route \
  -H "x-api-key: pk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "origin": { "type": "Point", "coordinates": [-73.9857, 40.7484] },
    "destination": { "type": "Point", "coordinates": [-73.9680, 40.7614] },
    "mode": "auto",
    "depart_at": "2026-03-23T08:00:00Z"
  }'
```

```
import Plaza from "@plazafyi/sdk";


const client = new Plaza();


const route = await client.v1.route({
  origin: { type: "Point", coordinates: [-73.9857, 40.7484] },
  destination: { type: "Point", coordinates: [-73.9680, 40.7614] },
  mode: "auto",
  depart_at: "2026-03-23T08:00:00Z",
});


console.log(`Duration with traffic: ${route.properties.duration_s}s`);
```

```
import plaza


client = plaza.Client()


route = client.v1.route(
    origin={"type": "Point", "coordinates": [-73.9857, 40.7484]},
    destination={"type": "Point", "coordinates": [-73.9680, 40.7614]},
    mode="auto",
    depart_at="2026-03-23T08:00:00Z",
)
print(f"Duration with traffic: {route['properties']['duration_s']}s")
```

## Comparing with and without traffic

Request the same route with and without `depart_at` to see the traffic impact:

Terminal window

```
# Without traffic (free-flow estimate)
curl -X POST https://plaza.fyi/api/v1/route \
  -H "x-api-key: pk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "origin": { "type": "Point", "coordinates": [-73.9857, 40.7484] },
    "destination": { "type": "Point", "coordinates": [-73.9680, 40.7614] },
    "mode": "auto"
  }'


# With Monday morning rush hour traffic
curl -X POST https://plaza.fyi/api/v1/route \
  -H "x-api-key: pk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "origin": { "type": "Point", "coordinates": [-73.9857, 40.7484] },
    "destination": { "type": "Point", "coordinates": [-73.9680, 40.7614] },
    "mode": "auto",
    "depart_at": "2026-03-23T08:00:00Z",
    "traffic_model": "pessimistic"
  }'
```

## How it works

Plaza maintains historical traffic profiles partitioned by hour (0–23) and day type (weekday vs. weekend). When you provide `depart_at`, the routing engine adjusts edge costs using speed factors from the traffic profile:

- A speed factor of `1.0` means free-flow conditions
- A speed factor of `0.5` means travel takes twice as long as free-flow
- The adjusted cost is: `base_cost / speed_factor`

This affects both route selection (the engine may prefer different roads during rush hour) and the reported `duration_s`.