Traffic-Aware Routing

Traffic-Aware Routing extends Directions 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 — 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 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

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:

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