Google Maps legacy APIs are going away — when and how to migrate?

Decide how and when to migrate from legacy Places, Directions, and Distance Matrix APIs to newer replacements given legacy status, changed SKU mappings, field-mask behavior, and different billing outcomes.

Stay on legacy only if already enabled. Migrate Places first — Routes API can follow. Do a coordinated cutover at the start of a billing month to avoid double-charging.

Blockers

Who this is for

Candidates

Stay on legacy temporarily, but only on already-enabled projects

As of 2026-03-15, existing projects can still use Places API, Directions API, and Distance Matrix API, but Google marks them as Legacy, feature-frozen, and unavailable to new Cloud projects. This is the lowest-change option when production stability matters more than immediate pricing or feature gains.

When to choose

Best for enterprise + compliance or high-scale + real-time systems where the legacy APIs are already enabled, the current behavior is deeply embedded, and you need a short controlled runway to inventory request shapes, billing, and response dependencies before migrating. Use this only as a temporary holding pattern, not a long-term default, especially if you operate multiple services and need time to coordinate a phased rollout.

Tradeoffs

You avoid immediate code churn and preserve current response formats such as legacy XML or default field behavior. The tradeoff is that Legacy services do not receive new feature development, are not available in new projects, and do not get the expanded automatic volume discounts that Google applies to the updated services.

Cautions

As of 2026-03-15, Google documents Legacy services as not available in new Cloud projects and says they only retain automatic volume discounts scaling to 100,000+ monthly billable events. There is no retirement date yet, but Google says Legacy is an intermediate stage before decommissioning and promises at least 12 months notice before shutdown. Check official docs before depending on legacy for any new project or environment.

Sources

Migrate Places first, keep legacy routing temporarily

As of 2026-03-15, this is the cleanest phased path when place search, autocomplete, and place details are your main correctness or billing risk. Places API (New) requires field masks for Place Details, Nearby Search, and Text Search, bills at the highest SKU represented in the field mask, and changes response semantics such as using `name` for the place resource name while `displayName` becomes the human-readable name.

When to choose

Best for cost-sensitive + small-team or low-ops + serverless stacks where autocomplete and place details dominate usage, and you can audit every returned field before touching routing. This is especially suitable when your routing behavior is stable but your place payloads are oversized, inconsistent, or still rely on legacy default-field habits.

Tradeoffs

You can capture Places-specific gains first, including IDs-only and Essentials-only request patterns, OAuth support, and explicit response shaping. The tradeoff is a mixed estate during migration, with two API generations, changed response schemas, JSON-only responses, and the need to manage exact field masks so a seemingly small field addition does not jump a request to Pro or Enterprise pricing.

Cautions

As of 2026-03-15, Google recommends migrating near the beginning of a month because old and new SKUs tier separately during the transition month. Google also recommends separate API keys if you run Places API (Legacy) and Places API (New) at the same time. Billing can escalate unexpectedly: `places.displayName` is a Pro field for web service responses, and if an Autocomplete session is terminated by a Place Details call requesting any Pro, Enterprise, or Enterprise + Atmosphere field, Google bills that termination at the Place Details Enterprise + Atmosphere rate. For pricing as of 2026-03-15, check official docs: Place Details Essentials remains in the Essentials pricing tier, while Place Details Pro, Enterprise, and Enterprise + Atmosphere use higher tiers.

Sources

Migrate Directions and Distance Matrix first to Routes API

As of 2026-03-15, this is the strongest phased path when route latency, matrix scale, or advanced routing features are the main driver. Routes API requires field masks, bills one SKU per request or per matrix element based on the highest feature tier used, and gives Compute Route Matrix a larger standard limit than Distance Matrix API for many workloads.

When to choose

Best for high-scale + real-time or microservices + enterprise systems where route computation is the hot path, especially dispatch, ETA, fleet, or travel-time ranking flows. Choose this when you can actively gate expensive features such as traffic-aware routing, waypoint optimization, toll calculation, or two-wheeler routing behind explicit product requirements instead of turning them on globally.

Tradeoffs

You get access to the newer routing surface, explicit response shaping, streaming matrix responses, and larger documented matrix limits. The tradeoff is that you must rewrite request and response handling, adopt field masks everywhere, and understand new SKU triggers so advanced routing modifiers do not silently move requests from Essentials to Pro or Enterprise.

Cautions

As of 2026-03-15, Compute Route Matrix is billed per element, not per whole request, and Google documents a maximum of 625 elements normally but only 100 elements when `routingPreference` is `TRAFFIC_AWARE_OPTIMAL`. Google also documents that Routes Pro is triggered by features such as 11 to 25 intermediate waypoints, `optimizeWaypointOrder=true`, `TRAFFIC_AWARE`, `TRAFFIC_AWARE_OPTIMAL`, side-of-road, heading, or vehicle-stopover modifiers, while Routes Enterprise is triggered by two-wheeled vehicle routing, toll calculation, and traffic information on polylines. For pricing as of 2026-03-15, check official docs: the public price list shows Routes Essentials at the same base tier as legacy Directions and Distance Matrix, but the new Routes SKUs have broader discount ladders beyond 100,000 monthly billable events.

Sources

Do one coordinated cutover to Places API (New) and Routes API at the start of a month

As of 2026-03-15, this is the best clean-state option when you want one migration window, one observability pass, and the fullest access to the updated pricing model. Google explicitly recommends switching to the new APIs as close to the beginning of the month as possible because legacy and updated SKUs bill separately during the transition month.

When to choose

Best for monorepo + small-team or enterprise + compliance environments where you can coordinate schema, test fixtures, billing review, and rollout controls in one release train. This is the strongest choice for greenfield services, major rewrites, or mature teams that can validate field masks, payload diffs, and product-tier triggers before production cutover.

Tradeoffs

You minimize the time spent in a mixed-generation setup and can re-baseline billing, telemetry, and contracts once. The tradeoff is higher migration intensity: both places and routing responses change, field-mask discipline becomes mandatory on both surfaces, and any billing mistake can affect multiple user flows at once.

Cautions

As of 2026-03-15, both Places and Routes migrations carry separate response and billing changes, so do not treat this as a simple endpoint swap. Places API (New) and Routes both return errors if required field masks are omitted, and Google warns against wildcard field masks in production because they can increase cost and latency. Recheck the live pricing list and SKU details before the cutover because price tables and SKU notes are policy-sensitive.

Sources

Facts updated: 2026-03-15
Published: 2026-03-29

Related questions

Try with your AI agent

$ npm install -g pocketlantern
$ pocketlantern init
# Restart Claude Code, Cursor, or your MCP client, then ask:
# "Google Maps legacy APIs are going away — when and how to migrate?"
Missing something? Request coverage