Directions API: Complete Developer Guide

Getting Started with Directions API

The Directions API calculates routes between locations. It supports driving, walking, bicycling, and transit modes with real-time traffic consideration.

Basic Request

GET /directions/json?
  origin=37.7749,-122.4194
  &destination=34.0522,-118.2437
  &mode=driving
  &key=YOUR_API_KEY

Adding Waypoints

Route through intermediate points using the waypoints parameter:

GET /directions/json?
  origin=San+Francisco
  &destination=Los+Angeles
  &waypoints=optimize:true|Fresno|Bakersfield
  &key=YOUR_API_KEY

The optimize:true prefix tells the API to reorder waypoints for the most efficient route — essential for delivery and logistics applications.

Traffic-Aware Routing

Add departure_time=now to get routes that account for current traffic conditions:

GET /directions/json?
  origin=37.7749,-122.4194
  &destination=37.3382,-121.8863
  &departure_time=now
  &traffic_model=best_guess
  &key=YOUR_API_KEY

The response includes duration_in_traffic alongside the standard duration field, giving you both ideal and realistic ETAs.

Alternative Routes

Set alternatives=true to receive up to 3 different route options. This is useful for ride-hailing apps where drivers may prefer different routes.

Response Structure

The response contains routes, each with legs (origin to waypoint, waypoint to waypoint, etc.), and each leg contains steps with turn-by-turn instructions:

• routes[].legs[].distance — total distance in meters and text
• routes[].legs[].duration — estimated travel time
• routes[].legs[].steps[] — individual navigation instructions
• routes[].overview_polyline — encoded polyline for map rendering

Cost Optimization

Directions API requests cost $5/1,000 on Google. On Beta, the Scale plan at $599/mo includes 1M requests ($0.60/1K). For a fleet management app making 10,000 daily route calculations (300K/mo), Beta's Growth plan at $199/mo saves over $1,300/month vs. Google.

Error Handling

Always handle these common status codes: ZERO_RESULTS (no route found), MAX_WAYPOINTS_EXCEEDED (limit is 25), and OVER_QUERY_LIMIT (rate limited). Implement exponential backoff for rate limit errors.