La version 3 de l’API Google Map est sortie en cours d’année 2010. Cette version est conçue pour se charger plus rapidement que la V2, est optimisée pour les smartphones (iOS et Android par exemple) et elle dispose de nouvelles fonctionnalités.

Que des bénéfices donc de migrer les codes de l’API V2 vers l’API V3… Malheureusement la V3 est une refonte quasi totale de l’API Google Map. Il faut donc réécrire la majorité du code, passer des heures à trouver les équivalents aux codes de la V2.

Charger l’API, initialiser la carte, ajouter des marqueurs personnalisés, charger un fichier XML, tracer des Polylines, afficher des Tooltips, aucun de ces codes V2 ne fonctionne en V3 !
Voici quelques portions de code qui pourront vous être utiles si vous vous lancez dans la migration de vos codes Google Map.

[js title=”Chargement de l'API V2″]<script type="text/javascript" src="http://maps.google.com/maps?file=api&v=2&key=ABQ…3fw"></script>[/js]
[js title=”Chargement de l'API V3″]<script type="text/javascript" src="http://maps.google.com/maps/api/js?sensor=false"></script>[/js]

Bon point, plus besoin de clé pour charger l’API. Le code ne sera donc plus lié au domaine sous lequel vous l’utilisez.

[js title=”Initialisation de la carte V2″]if (GBrowserIsCompatible()) {
map = new GMap2(document.getElementById(‘map’));
map.addControl(new GLargeMapControl());
map.addControl(new GMapTypeControl());
map.setCenter(new GLatLng(48.5, 2.9), 8);
}[/js]
[js title=”Initialisation de la carte V3″]var optionsCarte = {
zoom: 8,
center: new google.maps.LatLng(48.5, 2.9),
mapTypeId: google.maps.MapTypeId.ROADMAP
};
var map = new google.maps.Map(document.getElementById("map"), optionsCarte);[/js]

La V3 n’est pas compatible avec Internet Explorer 6, devenu clairement obsolète depuis quelques mois.
Il n’y a pas de type de map par défaut, il faut donc l’initialiser, sur ROADMAP (carte) par exemple.

[js title=”Icône personnalisée V2″]var baseIcon = new GIcon();
baseIcon.iconSize=new GSize(32,32);
baseIcon.shadowSize=new GSize(56,32);
baseIcon.iconAnchor=new GPoint(16,32);
baseIcon.infoWindowAnchor=new GPoint(16,0);
mon_icone = new GIcon(baseIcon, ‘http://maps.google.com/mapfiles/kml/pal2/icon13.png’,
null,
‘http://maps.google.com/mapfiles/kml/pal2/icon13s.png’);[/js]
[js title=”Icône personnalisée V3″]var imageMarqueur = new google.maps.MarkerImage(‘http://maps.google.com/mapfiles/kml/pal2/icon13.png’,
new google.maps.Size(32, 32),
new google.maps.Point(0,0),
new google.maps.Point(16, 32));
var ombreMarqueur = new google.maps.MarkerImage(‘http://maps.google.com/mapfiles/kml/pal2/icon13s.png’,
new google.maps.Size(56, 32),
new google.maps.Point(0,0),
new google.maps.Point(16, 32));[/js]

Le premier paramètre de MarkerImage est l’url de l’image, puis ses dimensions, l’angle supérieur gauche (toujours 0,0 pour une image unique mais peut être différent dans le cas d’un sprite

[matrice de plusieurs images]), et le point d’ancrage de l’icône.

[js title=”Ajouter un marqueur V2″]var point = new GLatLng(lat,lng);
var marker = new GMarker(point,mon_icone);
map.addOverlay(marker);[/js] [js title=”Ajouter un marqueur V3″]var point = new google.maps.LatLng(lat,lng);
var marker = new google.maps.Marker({
position: point,
map: map,
icon: imageMarqueur,
shadow: ombreMarqueur,
});[/js]

A noter qu’il n’est plus possible de supprimer tous les marqueurs avec un simple clearOverlays() :-(. Il faut maintenant créer un tableau des marqueurs puis boucler sur ce tableau pour supprimer les marqueurs de la carte seulement ou de la carte et du tableau (documentation officielle).

[js title=”Ajouter un polyline V2″]var poly = [];
var bounds = new GLatLngBounds;
for (var h = 0; h < points.length; h++) {
poly[h] = new GLatLng(parseFloat(points[h].getAttribute(‘lat’)), parseFloat(points[h].getAttribute(‘lng’)));
bounds.extend(poly[h]);
}
map.setCenter(bounds.getCenter());
map.setZoom(map.getBoundsZoomLevel(bounds));
map.addOverlay(new GPolyline(poly, ‘#FF0000’, 1, 0.8));[/js] [js title=”Ajouter un polyline V3″]var poly = [];
var bounds = new google.maps.LatLngBounds();
for (var h = 0; h < points.length; h++) {
poly[h] = new google.maps.LatLng(parseFloat(points[h].getAttribute(‘lat’)), parseFloat(points[h].getAttribute(‘lng’)));
bounds.extend(poly[h]);
}
monPolyline = new google.maps.Polygon({
paths: poly,
strokeColor: ‘#FF0000’,
strokeOpacity: 0.8,
strokeWeight: 1
});
monPolyline.setMap(map);
map.fitBounds(bounds);[/js]

Le tableau points est issu d’un fichier xml, il vient peupler le tableau poly qui comporte les coordonnées des différents points du polygone. Sans xml il peut être peuplé manuellement avec new google.maps.LatLng(latitude, longitude). Exemple poly = [new google.maps.LatLng(lat1, long1), new google.maps.LatLng(lat2, long2), …].
bounds.extend() est commun à la V2 et V3 (ouais !), cela étend les limites de la carte au fur et à mesure que les points du polygone sont ajoutés.
Dans la V3 map.fitBounds(bounds) ajustera le zoom de la carte pour que l’ensemble du polygone soit visible.

[js title=”Intégrer des marqueurs depuis un fichier xml V2″]GDownloadUrl("example.xml", function(doc) {
var xmlDoc = GXml.parse(doc);
var markers = xmlDoc.documentElement.getElementsByTagName("marker");
});[/js] [js title=”Intégrer des marqueurs depuis un fichier xml V3″]downloadUrl("example.xml", function(doc) {
var xmlDoc = xmlParse(doc);
var markers = xmlDoc.documentElement.getElementsByTagName("marker");
});[/js]

L’API V3 n’intègre plus les fonctions GDownloadUrl et GXml.parse… Il faut donc passer par un script externe pour retrouver les mêmes fonctionnalités que sur la V2. Vous trouverez un exemple complet ici.

Comme vous pouvez le constater, convertir ses scripts V2 en V3 n’est pas une partie de plaisir et fait perdre beaucoup de temps. Au delà de l’optimisation que peut apporter l’utilisation de la V3, la question que l’on peut se poser est combien de temps l’API V2 restera accessible auprès de Google ?

Si vous avez le courage de vous lancer dans la migration de votre code, la documentation officielle sera indispensable.