Anche se la fase di test e sviluppo non è ancora terminata, è possibile utilizzare la versione 3 delle Api di Google Maps (documentazione e reference) già da maggio 2009, data del loro annuncio: nonostante la somiglianza con la versione precedente (V.2), le nuove API beneficiano di un codice totalmente riscritto dagli sviluppatori di Mountain View. Vediamo in sintesi le principali novità.
- La differenza fondamentale è che l'API key non serve più, quindi non è necessario richiedere una nuova key per ogni dominio in cui si vuole includere una mappa.
- Sono state eliminate tutte le variabili globali della vecchia versione adottando un nuovo namespace (
google.maps). Inoltre, grazie alla nuova architettura MVC, il codice è ancora più modulare e "object oriented", con l'utilizzo di comodi oggetti messi a disposizione dalle API. - Dal punto di vista dell'ottimizzazione i tempi di caricamento della mappa sono stati ridotti grazie al minor peso (circa 35 kb) del JavaScript; inoltre è stato incorporato il sistema delle "static maps" per ridurre la percezione della latenza di caricamento.
- Un ottimo lavoro è stato fatto per migliorare la compatibilità con i browser di dispositivi mobili e smartphone (iPhone e Android in particolare).
- L'interfaccia di controllo della mappa è attivata automaticamente: con le nuove API non c'è bisogno di aggiungere i controlli di zoom o di tipo di mappa.
Nelle prossime pagine analizziamo alcune delle modalità di impiego più comuni: creazione della mappa, inserimento di segnaposti e suggerimenti testuali, geocoding e ricerca degli indirizzi delle località, calcolo di percorsi automobilistici o pedonali.
Creare una mappa
Tanto per cominciare, è necessario includere nel tag head della pagina lo script delle API di Google Maps. Da notare in querystring nell'indirizzo dello script la mancanza dell'API key e la presenza del parametro sensor, utilizzato dai dispositivi che dispongono di un gps per identificare la posizione attuale dell'utente. Volendo " localizzare la mappa", è possibile settare la lingua preferita in una variabile aggiuntiva language.
<script type="text/javascript" src="http://maps.google.com/maps/api/js?sensor=true&language=it"></script>Fatto questo possiamo analizzare i metodi delle API per costruire la mappa e scrivere un po' di codice Javascript.
Per inizializzare la mappa abbiamo bisogno innanzitutto di chiamare il costruttore della classe Map (google.maps.Map) che accetta due argomenti. Il primo è un riferimento a un elemento HTML in cui si desidera la mappa da inserire (spesso <div id="map">), il secondo è un oggetto contenente un insieme di proprietà:
| Proprietà | Descrizione |
|---|---|
| center | fissa il centro della mappa in base alle coordinate inserite nell'oggetto google.maps.LatLng |
| zoom | un intero che definisce il livello iniziale di zoom della mappa |
| mapTypeId | definisce il tipo di mappa tra HYBRID, ROADMAP, SATELLITE e TERRAIN |
Tra le altre numerose opzioni disponibili sono particolarmente utili quelle che consentono di personalizzare i vari controlli della mappa:
| Opzione | Descrizione |
|---|---|
| disableDefaultUI | booleano, valore di default false, consente di nascondere completamente i controlli della mappa |
| mapTypeControl, navigationControl, scaleControl, etc. | Questi semplici strumenti sono ampiamente documentati nella reference ufficiale delle nuove API. |
Un Esempio di mappa
Dato per assunto di conoscere le coordinate di latitudine e longitudine del centro della mappa, ecco il codice minimale del primo esempio:
<html>
<head>
<meta name="viewport" content="initial-scale=1.0, user-scalable=no"/>
<meta http-equiv="content-type" content="text/html; charset=UTF-8"/>
<title>Google Maps API v3: esempio base</title>
<script type="text/javascript" src="http://maps.google.com/maps/api/js?sensor=false"></script>
<script type="text/javascript">
var initialize = function() {
// fornisce latitudine e longitudine
var latlng = new google.maps.LatLng(42.745334,12.738430);
// imposta le opzioni di visualizzazione
var options = { zoom: 12,
center: latlng,
mapTypeId: google.maps.MapTypeId.ROADMAP
};
// crea l'oggetto mappa
var map = new google.maps.Map(document.getElementById('map'), options);
}
window.onload = initialize;
</script>
</head>
<body style="margin:0; padding:0;">
<div id="map" style="width:100%; height:100%"></div>
</body>
</html>Aggiungiamo i marcatori
Attraverso i Marker è possibile evidenziare i punti di interesse su una mappa. L'oggetto marker dispone del namespace google.maps.Marker e accetta un unico argomento, options, un oggetto letterale che può contenere diverse proprietà, di cui due obbligatorie:
| Proprietà | Descrizione |
|---|---|
| map | un riferimento alla mappa in cui si desidera aggiungere il marker |
| position | indica la posizione del marcatore ed è del tipo google.maps.LatLng |
Possiamo aggiungere il seguente codice e vedere il nuovo esempio:
var marker = new google.maps.Marker({ position: latlng,
map: map,
title: 'Questo è un testo di suggerimento' });Con molta semplicità anche con le API V.3 è possibile cambiare l'icona di default del marker tramite queste altre proprietà:
| Proprietà | Descrizione |
|---|---|
| icon | può contenere l'indirizzo di una icona personalizzata |
| shadow | imposta l'ombra del marker e può contenere il collegamento a una immagine |
| flat | booleano, se impostato su true disabilita l'ombra del marcatore |
Geocoding e ricerca degli indirizzi delle località
Geocoding è il processo di conversione di un indirizzo testuale (Viale Franco Angeli, 5 - Roma) in coordinate geografiche (latitudine, come 41.8963364 e longitudine 12.5777451), che è possibile utilizzare per varie operazioni come posizionare i marcatori o specificare il centro della stessa mappa.
L'API di Google Maps V.3 fornisce una classe geocoder per la geocodifica di indirizzi dinamici derivanti dall'input dell'utente: l'accesso al servizio di geocoding avviene istanziando l'oggetto google.maps.Geocoder, il quale dispone del metodo geocode() che avvia una richiesta passando due argomenti, il letterale GeocodeRequest e una funzione di callback da eseguire una volta completata la richiesta. L'oggetto GeocodeRequest può contenere diverse proprietà; una obbligatoria, address, che permette di specificare l'indirizzo testuale della ricerca, o in alternativa latLng, qualora si volessero passare le coordinate per effettuare un reverse geocoding. La risposta ottenuta dalla richiesta (GeocodeResults) è un oggetto JSON che con Javascript possiamo facilmente percorrere per ottenere le proprietà e le informazioni che ci interessano:
- formatted_address è una stringa contenente la versione formattata dell'indirizzo della posizione richiesta.
- address_component [] è un array contenente varie voci testuali con informazioni sull'indirizzo specificato.
- geometry contiene verie informazioni riguardo le coordinate: a fini pratici ricordiamo la proprietà position che rappresenta l'oggetto latLng con la latitudine e longitudine dell'indirizzo richiesto.
Attraverso il valore restiuito GeocoderStatus possiamo monitorare l'esito della richiesta: prima di utilizzare le informazioni contenute nelle risposta del geocoder e di creare la mappa, è bene infatti verificare che la richiesta abbia avuto successo e siano disponibili dei risultati verificando l'esistenza di Google.maps.GeocoderStatus.OK.
Non rimane che controllare il codice necessario e vedere l'esempio del geocoding.
<html>
<head>
<meta name="viewport" content="initial-scale=1.0, user-scalable=no"/>
<meta http-equiv="content-type" content="text/html; charset=UTF-8"/>
<title>Google Maps API v3: geocoding</title>
<script type="text/javascript" src="http://maps.google.com/maps/api/js?sensor=true"></script>
<script type="text/javascript">
var createMap = function() {
searchAddress();
var address = document.getElementById("address").value;
var geocoder = new google.maps.Geocoder();
geocoder.geocode( {'address': address}, function(results,status) {
if (status == google.maps.GeocoderStatus.OK) {
var options = {
zoom: 12,
center: results[0].geometry.location,
mapTypeId: google.maps.MapTypeId.ROADMAP
};
var map = new google.maps.Map(document.getElementById('map'), options);
var marker = new google.maps.Marker({position: results[0].geometry.location, map: map});
} else {
alert("Problema nella ricerca dell'indirizzo: " + status);
}
});
}
var searchAddress = function(){
document.getElementById("submit").onclick = function() {
createMap();
}
}
window.onload = createMap;
</script>
</head>
<body>
<div>
<input id="address" type="textbox" value="Viale Franco Angeli, 5 - Roma">
<input id="submit" type="button" value="trova indirizzo sulla mappa">
</div>
<div id="map"></div>
</body>
</html>Directions
Sicuramente una delle funzionalità più interessanti delle API V.3 è directions, che consente il calcolo del percorso tra due località e la visualizzazione sulla mappa con un disegno polyline in aggiunta a una serie di marker con descrizione testuale.
Il supporto a directions è possibile attraverso due nuove classi, DirectionsRenderer e DirectionsService, fondamentalmente una delegata alla visualizzazione, l'altra allo svolgimento del calcolo delle direzioni.
Creata una nuova istanza della classe DirectionsService, è necessario effettuare una richiesta tramite il metodo DirectionsService.route() che opera con modalità simili a quelle viste per Geocoder.geocode(): sono necessari due argomenti, il letterale DirectionsRequest e la funzione di callback eseguita appena la richiesta è stata completata. L'oggetto DirectionsRequest può contenere le seguenti proprietà:
- origin (obbligatorio) specifica l'indirizzo di partenza da cui calcolare il percorso.
- destination (obbligatorio) specifica l'indirizzo di arrivo del percorso: origin e destination possono essere valori specificati come una stringa (ad esempio, "Roma, via dei Condotti") o come un oggetto
latLng. - travelMode (obbligatorio) specifica la modalità di trasporto (DRIVING o WALKING).
- waypoint [] (opzionale) specifica un array (DirectionsWaypoints) di punti di passaggio obbligati nel calcolo del percorso.
La funzione di callback restituisce un codice DirectionsStatus con l'esito della richiesta e un oggetto in formato JSON, DirectionsResult, che presenta una struttura articolata contenente le indicazioni per la localizzazione dei punti di arrivo e partenza (oltre ad altre informazioni come ad esempio la durata e la lunghezza del percorso).
A questo punto è necessario inizializzare l'altra classe, DirectionsRenderer. La nuova istanza deve essere associata tramite il metodo setMap() ad una mappa nella pagina creata con le normali modalità. Infine sempre su questa istanza è necessario invocare un ulteriore metodo, che accetta come argomento l'oggetto della risposta DirectionsResult e che si occupa di disegnare il percorso sulla mappa: si tratta di setDirections().
Un esempio e l'esame del codice rende più semplice la comprensione del funzionamento dello script. Tramite il metodo setPanel() è possibile visualizzare indicazioni testuali del percorso in un div appositamente inserito nella pagina: ecco l'ultimo esempio con una variante per il calcolo di un tragitto pedonale.
Conclusioni
L'implementazione di Google maps tramite le nuove API V.3 offre l'opportunità di sperimentare una metodologia di programmazione molto logica ed efficace, un codice snello e modulare che mostra appieno tutti i vantaggi della programmazione orientata agli oggetti: nella pratica il tutto agevola la scala di apprendimento e conseguentemente si traduce in una ancora maggiore semplicità di utilizzo rispetto alla vecchia versione.
Il codice e gli esempi sono disponibili per il download.
