Le deprecazioni delle API Google Maps arrivano a maggio 2026: checklist di migrazione per sviluppatori

Google ha progressivamente ristretto la sua Maps Platform negli ultimi anni, ma l'ondata di deprecazioni di maggio 2026 è la più impattante finora. Quattro funzionalità ampiamente utilizzate vengono rimosse dalla Maps JavaScript API: Heatmap Layer, Drawing Library, DirectionsService e DistanceMatrixService. Se la tua applicazione dipende da una di esse, hai poche settimane per migrare prima che il codice smetta di funzionare.

Non si tratta di una deprecazione morbida in cui i vecchi endpoint restano disponibili per anni. Google ha fissato date di rimozione definitive e la console sviluppatori mostra già degli avvisi. Questa guida spiega esattamente cosa sta cambiando, perché Google sta facendo queste modifiche e come migrare ogni servizio con esempi di codice funzionanti. Se hai bisogno di un sostituto diretto, ti mostriamo come le API MapAtlas corrispondono a ciascun servizio Google deprecato.

Cosa viene deprecato e quando

Ecco la cronologia completa dei servizi interessati:

Il dettaglio critico: Google non sta eliminando il routing e i calcoli delle distanze nella loro interezza. Sta eliminando le classi JavaScript lato client che gli sviluppatori usano da oltre un decennio e sta imponendo la migrazione alla nuova Routes API, un endpoint REST lato server. Non è un semplice aggiornamento di versione: è un cambiamento architetturale che sposta la logica di routing dal browser al tuo backend.

Cosa smette di funzionare

Se il tuo codebase contiene uno degli elementi seguenti, fallirà dopo la data di rimozione:

// All of these will stop working in May 2026
const directionsService = new google.maps.DirectionsService();
const distanceMatrixService = new google.maps.DistanceMatrixService();
const heatmap = new google.maps.visualization.HeatmapLayer({ data: points });
const drawingManager = new google.maps.drawing.DrawingManager();

Dopo la rimozione, questi costruttori genereranno errori. Non c'è nessun comportamento di fallback, nessuna degradazione graduale. La mappa si caricherà, ma qualsiasi funzionalità che dipende da queste classi si romperà completamente.

Perché Google impone questi cambiamenti

La giustificazione ufficiale di Google è performance e modernizzazione. La Routes API, il sostituto di DirectionsService e DistanceMatrixService, supporta funzionalità più recenti come il routing eco-friendly, il routing per veicoli a due ruote e la stima dei pedaggi, che le classi JavaScript legacy non possono supportare.

Il vero motore è il controllo dei prezzi. Spostando il routing su una REST API lato server, Google ottiene una fatturazione più granulare e un monitoraggio più preciso dell'utilizzo. Il DirectionsService JavaScript consentiva pattern di batching lato client che per Google erano più difficili da misurare con precisione. La Routes API garantisce che ogni richiesta passi attraverso un endpoint misurato.

Per Heatmap Layer e Drawing Library, Google sta spingendo gli sviluppatori verso la sua Extended Component Library e strumenti di visualizzazione di terze parti come deck.gl. È parte di un pattern più ampio: Google mantiene il rendering dei tile della mappa internamente e esternalizza tutto il resto all'ecosistema.

L'impatto pratico per gli sviluppatori è una maggiore infrastruttura backend, più API key da gestire e, nella maggior parte dei casi, costi per richiesta più elevati sui nuovi livelli di prezzo.

Checklist di migrazione

Prima di scrivere qualsiasi codice di migrazione, segui questa checklist:

1. Fai un audit del codebase

Cerca nel tuo codebase i riferimenti alle classi deprecate:

# Find all files using deprecated Google Maps services
grep -rn "DirectionsService\|DistanceMatrixService\|HeatmapLayer\|visualization.HeatmapLayer\|drawing.DrawingManager\|DrawingManager" \
  --include="*.js" --include="*.ts" --include="*.tsx" --include="*.jsx" src/

Documenta ogni file e componente che usa questi servizi. Annota se le chiamate avvengono lato client (browser) o in un contesto renderizzato lato server, come le API route di Next.js.

2. Identifica i tuoi pattern di utilizzo

Per ogni utilizzo, documenta:

• Modalità di viaggio usate (driving, walking, cycling, transit)
• Supporto waypoint (semplice A-verso-B o percorsi multi-tappa)
• Campi della risposta consumati (distanza, durata, polyline, tappe, tariffa)
• Volume (richieste al giorno/mese, per la stima dei costi)
• Requisiti di latenza (real-time per l'utente o elaborazione in batch)

3. Scegli il tuo obiettivo di migrazione

Hai due opzioni:

Opzione A: Restare con Google. Migrare dalle classi JavaScript deprecate alla nuova Google Routes API (REST). Questo richiede modifiche al backend, nuovi permessi per la API key e aggiornamento della fatturazione.

Opzione B: Cambiare provider. Migrare a una API di routing di terze parti. È il momento giusto per valutare le alternative, dato che stai comunque riscrivendo il codice di integrazione.

4. Configura un ambiente parallelo

Non migrare mai in-place. Esegui la vecchia e la nuova implementazione in parallelo per almeno due settimane, confrontando i risultati in termini di precisione e latenza prima di fare il cutover.

5. Aggiorna la gestione degli errori

I servizi deprecati restituivano gli errori tramite funzioni callback. I sostituti REST restituiscono codici di stato HTTP. La tua logica di gestione degli errori deve essere aggiornata di conseguenza.

Guida alla sostituzione API per API

DirectionsService verso MapAtlas Directions API

Prima (Google, deprecato):

const directionsService = new google.maps.DirectionsService();

directionsService.route(
  {
    origin: { lat: 52.52, lng: 13.405 },
    destination: { lat: 48.8566, lng: 2.3522 },
    travelMode: google.maps.TravelMode.DRIVING,
    waypoints: [
      { location: { lat: 50.9375, lng: 6.9603 }, stopover: true }
    ],
  },
  (result, status) => {
    if (status === "OK") {
      const route = result.routes[0];
      console.log("Distance:", route.legs[0].distance.text);
      console.log("Duration:", route.legs[0].duration.text);
    }
  }
);

Dopo (MapAtlas Directions API):

const response = await fetch(
  "https://api.mapatlas.com/v1/directions?" +
    new URLSearchParams({
      origin: "52.52,13.405",
      destination: "48.8566,2.3522",
      waypoints: "50.9375,6.9603",
      mode: "driving",
      key: process.env.MAPATLAS_API_KEY!,
    })
);

const data = await response.json();

if (data.status === "OK") {
  const leg = data.routes[0].legs[0];
  console.log("Distance:", leg.distance.text);
  console.log("Duration:", leg.duration.text);
  // Polyline for map rendering
  const polyline = data.routes[0].overview_polyline;
}

Differenze principali:

• Endpoint REST invece di una classe JavaScript. Le chiamate partono dal tuo backend, non dal browser.
• Autenticazione più semplice. Una sola API key nel query string o nell'header.
• Stessa struttura della risposta. Routes, legs, distance, duration e polyline sono tutti presenti.

DistanceMatrixService verso MapAtlas Matrix API

Prima (Google, deprecato):

const service = new google.maps.DistanceMatrixService();

service.getDistanceMatrix(
  {
    origins: [
      { lat: 52.52, lng: 13.405 },
      { lat: 48.1351, lng: 11.582 },
    ],
    destinations: [
      { lat: 48.8566, lng: 2.3522 },
      { lat: 51.5074, lng: -0.1278 },
    ],
    travelMode: google.maps.TravelMode.DRIVING,
  },
  (response, status) => {
    if (status === "OK") {
      response.rows.forEach((row, i) => {
        row.elements.forEach((element, j) => {
          console.log(`Origin ${i} -> Dest ${j}:`,
            element.distance.text, element.duration.text);
        });
      });
    }
  }
);

Dopo (MapAtlas Matrix API):

const response = await fetch("https://api.mapatlas.com/v1/matrix", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: `Bearer ${process.env.MAPATLAS_API_KEY}`,
  },
  body: JSON.stringify({
    origins: [
      { lat: 52.52, lng: 13.405 },
      { lat: 48.1351, lng: 11.582 },
    ],
    destinations: [
      { lat: 48.8566, lng: 2.3522 },
      { lat: 51.5074, lng: -0.1278 },
    ],
    mode: "driving",
  }),
});

const data = await response.json();

data.rows.forEach((row: any, i: number) => {
  row.elements.forEach((element: any, j: number) => {
    console.log(`Origin ${i} -> Dest ${j}:`,
      element.distance.text, element.duration.text);
  });
});

La struttura della risposta è quasi identica. Il cambiamento principale è passare da una API browser basata su callback a una API server basata su promise.

Sostituzione del Heatmap Layer

Per la visualizzazione heatmap, il percorso di migrazione dipende dai tuoi requisiti:

Opzione 1: MapLibre GL JS con heatmap layer (open source)

import maplibregl from "maplibre-gl";

const map = new maplibregl.Map({
  container: "map",
  style: "https://api.mapatlas.com/v1/styles/streets?key=YOUR_KEY",
  center: [13.405, 52.52],
  zoom: 10,
});

map.on("load", () => {
  map.addSource("heat-data", {
    type: "geojson",
    data: {
      type: "FeatureCollection",
      features: heatmapPoints.map((point) => ({
        type: "Feature",
        geometry: { type: "Point", coordinates: [point.lng, point.lat] },
        properties: { weight: point.weight },
      })),
    },
  });

  map.addLayer({
    id: "heatmap-layer",
    type: "heatmap",
    source: "heat-data",
    paint: {
      "heatmap-weight": ["get", "weight"],
      "heatmap-intensity": 1,
      "heatmap-radius": 20,
      "heatmap-opacity": 0.7,
    },
  });
});

Questo ti dà pieno controllo sul rendering della heatmap e non dipende dai tile server di Google.

Opzione 2: deck.gl HeatmapLayer (la raccomandazione ufficiale di Google)

import { Deck } from "@deck.gl/core";
import { HeatmapLayer } from "@deck.gl/aggregation-layers";

const heatmapLayer = new HeatmapLayer({
  data: heatmapPoints,
  getPosition: (d) => [d.lng, d.lat],
  getWeight: (d) => d.weight,
  radiusPixels: 30,
});

Entrambe le opzioni funzionano. MapLibre GL JS si integra in modo pulito con gli stili dei tile di MapAtlas, mentre deck.gl può essere sovrapposto a qualsiasi mappa base.

Confronto dei costi: Google Routes API vs. MapAtlas

Migrare alla Routes API di Google non è solo una questione di codice. Comporta anche nuovi prezzi:

Con 100.000 richieste di routing al mese:

• Google Routes API: circa $500-$1.000 (a seconda delle funzionalità usate)
• MapAtlas Directions API: circa $150-$250

Il risparmio cresce rapidamente per le applicazioni che combinano routing con geocoding e calcoli delle distanze. Una piattaforma logistica che elabora 500.000 elementi di matrice al mese pagherebbe circa $2.500 con Google contro $500 con MapAtlas.

Per tutti i dettagli sui prezzi, consulta i prezzi di MapAtlas.

Esempi completi di migrazione: prima e dopo

Ecco un esempio completo di migrazione per un componente React che mostra indicazioni stradali su una mappa.

Prima: Google Maps DirectionsService in React

import { useEffect, useRef } from "react";

function DirectionsMap({ origin, destination }: {
  origin: google.maps.LatLngLiteral;
  destination: google.maps.LatLngLiteral;
}) {
  const mapRef = useRef<HTMLDivElement>(null);

  useEffect(() => {
    const map = new google.maps.Map(mapRef.current!, {
      center: origin,
      zoom: 7,
    });

    const directionsRenderer = new google.maps.DirectionsRenderer();
    directionsRenderer.setMap(map);

    const directionsService = new google.maps.DirectionsService();
    directionsService.route(
      {
        origin,
        destination,
        travelMode: google.maps.TravelMode.DRIVING,
      },
      (result, status) => {
        if (status === "OK" && result) {
          directionsRenderer.setDirections(result);
        }
      }
    );
  }, [origin, destination]);

  return <div ref={mapRef} style={{ width: "100%", height: "400px" }} />;
}

Dopo: MapAtlas Directions API con MapLibre GL JS

import { useEffect, useRef } from "react";
import maplibregl from "maplibre-gl";

function DirectionsMap({ origin, destination }: {
  origin: { lat: number; lng: number };
  destination: { lat: number; lng: number };
}) {
  const mapRef = useRef<HTMLDivElement>(null);

  useEffect(() => {
    const map = new maplibregl.Map({
      container: mapRef.current!,
      style: "https://api.mapatlas.com/v1/styles/streets?key=YOUR_KEY",
      center: [origin.lng, origin.lat],
      zoom: 7,
    });

    map.on("load", async () => {
      // Fetch directions from your backend (or directly if CORS allows)
      const res = await fetch(
        `/api/directions?` +
          new URLSearchParams({
            origin: `${origin.lat},${origin.lng}`,
            destination: `${destination.lat},${destination.lng}`,
            mode: "driving",
          })
      );
      const data = await res.json();

      if (data.routes?.[0]) {
        const coordinates = data.routes[0].geometry.coordinates;

        map.addSource("route", {
          type: "geojson",
          data: {
            type: "Feature",
            geometry: { type: "LineString", coordinates },
            properties: {},
          },
        });

        map.addLayer({
          id: "route-line",
          type: "line",
          source: "route",
          paint: {
            "line-color": "#4A90D9",
            "line-width": 5,
          },
        });

        // Fit map to route bounds
        const bounds = coordinates.reduce(
          (b: maplibregl.LngLatBounds, coord: [number, number]) =>
            b.extend(coord),
          new maplibregl.LngLatBounds(coordinates[0], coordinates[0])
        );
        map.fitBounds(bounds, { padding: 50 });
      }
    });

    return () => map.remove();
  }, [origin, destination]);

  return <div ref={mapRef} style={{ width: "100%", height: "400px" }} />;
}

API Route backend (Next.js)

// app/api/directions/route.ts
import { NextRequest, NextResponse } from "next/server";

export async function GET(request: NextRequest) {
  const { searchParams } = new URL(request.url);
  const origin = searchParams.get("origin");
  const destination = searchParams.get("destination");
  const mode = searchParams.get("mode") || "driving";

  const response = await fetch(
    `https://api.mapatlas.com/v1/directions?` +
      new URLSearchParams({
        origin: origin!,
        destination: destination!,
        mode,
        key: process.env.MAPATLAS_API_KEY!,
      })
  );

  const data = await response.json();
  return NextResponse.json(data);
}

Questo pattern mantiene la tua API key sul server ed espone al client solo la geometria del percorso.

Come testare la migrazione prima della scadenza

Passo 1: Esegui entrambe le API in parallelo

Per due settimane prima del cutover, chiama sia il vecchio servizio Google che il nuovo sostituto per ogni richiesta. Registra entrambe le risposte e confrontale:

async function getDirectionsWithComparison(
  origin: string,
  destination: string
) {
  const [googleResult, mapatResult] = await Promise.all([
    fetchGoogleDirections(origin, destination),
    fetchMapAtlasDirections(origin, destination),
  ]);

  // Compare key metrics
  const distanceDelta = Math.abs(
    googleResult.distance - mapatResult.distance
  );
  const durationDelta = Math.abs(
    googleResult.duration - mapatResult.duration
  );

  console.log({
    route: `${origin} -> ${destination}`,
    googleDistance: googleResult.distance,
    mapatDistance: mapatResult.distance,
    distanceDeltaPercent: ((distanceDelta / googleResult.distance) * 100).toFixed(1),
    googleDuration: googleResult.duration,
    mapatDuration: mapatResult.duration,
    durationDeltaPercent: ((durationDelta / googleResult.duration) * 100).toFixed(1),
  });

  // Use MapAtlas result in production, Google as validation
  return mapatResult;
}

Passo 2: Configura i feature flag

Usa un feature flag per controllare quale API chiama la tua applicazione. Questo ti permette un rollback istantaneo in caso di problemi:

const useMapAtlasDirections = process.env.FEATURE_MAPATLAS_DIRECTIONS === "true";

const directions = useMapAtlasDirections
  ? await fetchMapAtlasDirections(origin, destination)
  : await fetchGoogleDirections(origin, destination);

Passo 3: Monitora i tassi di errore

Dopo il switch, monitora:

• Tassi di errore HTTP 4xx/5xx dalla nuova API
• Aumenti di latenza (il nuovo provider potrebbe avere tempi di risposta diversi)
• Campi mancanti nelle risposte da cui dipende la tua UI
• Precisione del percorso per casi limite (traghetti, strade a pedaggio, aree limitate)

Passo 4: Load test prima del go-live

Se la tua applicazione gestisce picchi di traffico, come una piattaforma logistica durante il dispatch mattutino, esegui un load test della nuova API al 2x del tuo volume di punta. MapAtlas offre un ambiente sandbox per il load testing senza incorrere in fatturazione di produzione.

Calendario: cosa fare questa settimana

Se non hai ancora iniziato la migrazione, ecco l'ordine di priorità:

1. Questa settimana: Fai un audit del codebase. Identifica ogni utilizzo dei quattro servizi deprecati.
2. Settimana 2: Crea un account MapAtlas e ottieni le API key. Il tier gratuito include 10.000 richieste per i test.
3. Settimana 3: Implementa il sostituto per il tuo servizio più critico (di solito DirectionsService).
4. Settimana 4: Migra i servizi rimanenti ed esegui test in parallelo.
5. Prima della scadenza di maggio: Fai il cutover, rimuovi le dipendenze dall'API Google, aggiorna la fatturazione.

La migrazione non è opzionale. Dopo maggio 2026, le classi deprecate saranno rimosse dalla Maps JavaScript API e qualsiasi codice che le referenzia genererà errori a runtime. Inizia adesso e avrai il tempo di testare correttamente. Aspetta l'ultima settimana e ti ritroverai a fare patch in produzione sotto pressione.

Per supporto alla migrazione, MapAtlas fornisce assistenza diretta agli sviluppatori. Contattaci tramite la pagina contatti o inizia dalla documentazione API per valutare le API sostitutive rispetto ai tuoi requisiti.