Directions API quick reference

Directions API (Legacy) is a web service that calculates directions between locations for driving, walking, bicycling, and transit, including multipart routes with waypoints, and returns routes, legs, and steps in JSON or XML. It's in Legacy status: as of October 2026 it can't be enabled for new Google Cloud projects; migrate to the Routes API.

Directions API: key facts

  • Product: Directions API
  • Also known as: Directions API (Legacy)
  • Category: Routes
  • Platform: Web service (REST)
  • Runs on: Server (backend code)
  • Launch stage: GA
  • Lifecycle: Legacy
  • Replaced by: Routes API
  • Overview: Directions API overview
  • Regional availability: Global. Coverage varies by region and travel mode (transit depends on data from transit providers). (coverage details)

Directions API: when to use it

Use Directions API when:

  • You maintain an existing Google Cloud project that already has Directions API (Legacy) enabled and calls maps/api/directions.
  • You need server-side directions for driving, walking, bicycling, or transit (waypoints for non-transit modes only), in JSON or XML, in an existing project.

Don't use Directions API when:

  • You're starting a new Google Cloud project; as of October 2026 Directions API (Legacy) can't be enabled for new projects. Use Routes API instead.
  • You need new routing features and improved performance. Use Routes API instead.
  • You need travel times and distances for many origins and destinations in one request. Use Routes API instead.

Directions API: setup

Directions API: common mistakes

  • Problem: Requests to Directions API (Legacy) from a project where the legacy API isn't enabled fail with LegacyApiNotActivatedMapError. Fix: If you own the app, migrate to the Routes API. As a short-term solution while you migrate or wait for an app update, you can activate the legacy API by completing the legacy API activation form. See /maps/legacy.
  • Problem: Using the via: prefix on waypoints makes them strict pass-throughs, which can cause severe detours or a ZERO_RESULTS status. Fix: Use stopover waypoints (no via: prefix) unless a strict pass-through point is required. See /maps/documentation/directions/get-directions.
  • Problem: Requests with 11 to 25 waypoints, optimize:true, traffic-aware durations (duration_in_traffic), or the side_of_road or heading location modifiers are billed at the higher Directions Advanced (Pro) SKU. Fix: Use these features only when you need them; keep waypoints at 10 or fewer and omit optimize:true, departure_time (for driving), side_of_road, and heading to stay on the Essentials SKU. See /maps/billing-and-pricing/sku-details/legacy#directions-advanced-pro-sku.
  • Problem: For driving, departure_time can't be in the past (the request fails with INVALID_REQUEST). Without departure_time, route and duration use average time-independent traffic, and no duration_in_traffic is returned. Fix: Set departure_time to now or a future time with mode=driving to get duration_in_traffic. Requests that return duration_in_traffic are billed at the Directions Advanced (Pro) SKU. See /maps/documentation/directions/get-directions.