La classe GClientGeocoder est utilisée pour communiquer directement avec les serveurs de Google dans le but d’obtenir les coordonnées géographiques d’une adresse (coordonnées représentées par ses latitude et longitude).
Cette classe dispose de son propre système de cache. Si l’utilisateur effectue plusieurs fois une recherche de coordonnées pour une même adresse, un seul appel sera réalisé sur les serveurs de Google.
Les coordonnées obtenues pour ce point seront alors stockées dans ce cache.
De manière générale, il faut éviter d’utiliser la classe GClientGeocoder pour récupérer un lot de coordonnées. On évitera par exemple d’appeler cette classe dans une boucle.
Pour géocoder un lot d’adresses avec Google Map, il est préférable d’avoir recours au service web de géocodage de Google (HTTP Geocoder) [bientôt en ligne].
Récupérer les coordonnées d’un point avec la classe GClientGeocoder
constructeur GClientGeocoder
Disponible depuis la version 2.55 de l’Api.
Signature du constructeur GClientGeocoder : GClientGeocoder(cache : GGeocodeCache [bientôt en ligne]).
Créé une nouvelle instance de géocodage qui communique directement avec les serveurs de Google.
Le paramètre optionnel cache permet de spécifier un cache personnalisé côté client pour des adresses connues. Si ce paramètre n’est pas renseigné, un objet de type GFactualGeocodeCache [bientôt en ligne] sera utilisé.
<script type="text/javascript">
var map = new GMap2(document.getElementById('map'), { size: new GSize(200,200)});
/* Ici, nous déclarons l'élément html ayant pour id "map" comme conteneur de la map
avec une taille de 200 * 200 pixel */
var geocoder = new GClientGeocoder();
/* Créé un objet de type GClientGeocoder, prêt à être utilisé. */
</script>
getLatLng()
Disponible depuis la version 2.55 de l’Api.
Signature de la méthode getLatLng : getLatLng(adresse : string, callback : fonction).
Cette méthode, appliquée à notre objet de type GClientGeocoder, envoie une requête aux serveurs de Google afin d’obtenir les coordonnées géographiques de l’adresse passée en paramètre.
Si l’adresse a pu être géolocalisée, la fonction de retour (callback) est invoquée avec un objet de type GLatLng en paramètre.
Le cas échéant, un point nul (null) est renvoyé à la fonction callback.
Dans les cas ambigus (plusieurs réponses pour une même adresse), seul le point jugé le plus pertinent est renvoyé à la fonction callback.
Pour récupérer l’ensemble des réponses (si plusieurs réponses il y a) voir la méthode getLocations.
Récupérer les coordonnées d’un point à partir d’une adresse
<script type="text/javascript">
var map = new GMap2(document.getElementById('map'), { size: new GSize(200,200)});
/* Ici, nous déclarons l'élément html ayant pour id "map" comme conteneur de la map
avec une taille de 200 * 200 pixel */
var geocoder = new GClientGeocoder();
/* Créé un objet de type GClientGeocoder, prêt à être utilisé. */
/* Déclaration de la fonction chargée de communiquer avec les serveurs de Google */
function geocodeMyAddress(adr){
if(adr != ''){ /* Si une adresse a été fournie */
/* Essai de géolocalisation auprès de Google */
geocoder.getLatLng(adr,function(point) {
if(!point) {
/* L'adresse n'a pu être géolocalisée */
alert("! "+adr+" n'existe pas ou n\'a pu être géolocalisée ...");
}else{
/* Géolocalisation ok. Un objet de type GPoint est renvoyé,
on récupère les coordonnées */
var a = point.lat();
var b = point.lng();
/* Affichage d'un marker avec infobulle */
var marker = new GMarker(point);
map.addOverlay(marker);
marker.openInfoWindowHtml(CONTENU INFO BULLE);
/* Centrage de la carte sur le point */
map.setCenter(new GLatLng(a,b), 12);
}}
);
}
}
</script>
getLocations (adresse)
Disponible depuis la version 2.55 de l’Api.
Signature de la méthode getLocations : getLocations(adresse : string, callback : fonction).
Cette méthode effectue un géocodage en convertissant une adresse postale en coordonnées géographiques. La méthode getLocations envoie alors une requête au service de géocodage de Google, en lui demandant de parser l’adresse passée en paramètre.
La réponse est ensuite envoyée à la fonction callback. Puisque cette méthode communique avec les serveurs de Google, il est nécessaire de déclarer une fonction callback pour traiter la réponse.
Cette réponse contiendra un code représentant le status de la requête (200 = ok, 602 = non trouvée, codes réponses du geocoder de Google) et si l’adresse a pu être géolocalisée, un ou plusieurs objets Placemark.
À noter qu’à partir de la version 2.133 de l’Api, cette méthode a été augmentée pour permettre de passer un objet de type GLatLng en paramètre pour le géocodage inversé comme expliqué dans le paragraphe suivant.
Récupérer un objet placemark à partir d’une adresse
<script type="text/javascript">
var map = new GMap2(document.getElementById('map'), { size: new GSize(200,200)});
/* Ici, nous déclarons l'élément html ayant pour id "map" comme conteneur de la map
avec une taille de 200 * 200 pixel */
var geocoder = new GClientGeocoder();
/* Créé un objet de type GClientGeocoder, prêt à être utilisé. */
/* Déclaration de la fonction chargée de communiquer avec les serveurs de Google */
function geocodeMyAddress(adr){
if(adr != ''){ /* Si une adresse a été fournie */
/* Essai de géolocalisation auprès de Google */
geocoder.getLocations(adr,function(point) {
if(!point) {
/* L'adresse n'a pu être géolocalisée */
alert("! "+adr+" n'existe pas ou n'a pu être géolocalisée ...");
}else if(point['Status']['code'] == 200){
isGeocode(point);
}}
);
}
}
/* Déclaration de la fonction chargée de traiter la réponse */
function isGeocode (point){
document.getElementById("answer").innerHTML = JSON.stringify (point);
}
Dans notre exemple, en recherchant la ville "Brest",
les fonctions geocodeMyAddress et isGeocode nous renvoient
les informations listées ci-dessous :
{
"name" : "brest",
"Status" : { "code" : 200, "request" : "geocode" },
"Placemark" :
[{
"id" : "p1",
"address" : "Brest, France",
"AddressDetails" :
{
"Accuracy" : 4,
"Country" :
{
"AdministrativeArea":
{
"AdministrativeAreaName" : "Brittany",
"SubAdministrativeArea" :
{
"Locality" : { "LocalityName" : "Brest" },
"SubAdministrativeAreaName" : "Finistere"
}
},
"CountryName" : "France",
"CountryNameCode" : "FR"
}
},
"ExtendedData" : { "LatLonBox" : { "north" : 48.4202334, "south" : 48.3609578,
"east" :-4.4228716, "west":-4.550931} },
"Point" :{ "coordinates" : [-4.4869013,48.3906042,0] }
}]
}
</script>
getLocations (latlng)
Disponible depuis la version 2.133 de l’Api.
Contrairement à la méthode
getLatLng, la méthode getLocations renvoie l’ensemble des résultats trouvés et non le point jugé le plus pertinent.
En fonction des besoins de votre application, vous pouvez ainsi choisir l’une ou l’autre de ces méthodes.
Signature de la méthode getLocations : getLocations(latlng : GLatLng, callback : fonction).
Cette méthode effectue un géocodage inversé en convertissant des coordonnées géographiques en une adresse postale.
Dans ce cas de figure, la méthode getLocations envoie alors une requête au service de géocodage de Google, en lui demandant de retourner l’adresse correspondant au point passé en paramètre.
La réponse est ensuite envoyée à la fonction callback. Puisque cette méthode communique avec les serveurs de Google, il est nécessaire de déclarer une fonction callback pour traiter la réponse.
Cette réponse contiendra un code représentant le status de la requête (200 = ok, 602 = non trouvée, …) et si l’adresse a pu être géolocalisée, un ou plusieurs objets Placemark.
À noter que la méthode getLocations peut également prendre en paramètre une adresse postale.
Récupérer une adresse à partir de ses coordonnées
<script type="text/javascript">
var geocoder = new GClientGeocoder();
/* Créé un objet de type GClientGeocoder, prêt à être utilisé. */
var pt = new GLatLng(48.3906042, -4.4869013);
/* Déclaration du point */
/* Déclaration de la fonction chargée de communiquer avec les serveurs de Google */
function geocodeMyAddress(pt){
if(adr != ''){ /* Si une adresse a été fournie */
/* Essai de géolocalisation auprès de Google */
geocoder.getLocations(pt,function(point) {
if(!point) {
/* L'adresse n'a pu être géolocalisée */
alert("! "+adr+" n'existe pas ou n'a pu être géolocalisée ...");
}else if(point['Status']['code'] == 200){
isGeocode(point);
}}
);
}
}
/* Déclaration de la fonction chargée de traiter la réponse */
function isGeocode (point){
document.getElementById("answer").innerHTML = JSON.stringify (point);
}
voir la réponse obtenue par les fonctions geocodeMyAddress et isGeocode
</script>
getCache()
Disponible depuis la version 2.55 de l’Api.
Signature de la méthode getCache : getCache().
Cette méthode retourne le cache utilisé (objet de type GGeocodeCache [bientôt en ligne]) pour le géocodage ou null si aucun cache n’est effectué côté client.
Lister le contenu du cache de la classe GClientGeocoder
<script type="text/javascript">
var geocoder = new GClientGeocoder();
/* Créé un objet de type GClientGeocoder, prêt à être utilisé. */
var pt = new GLatLng(48.3906042, -4.4869013);
/* Déclaration du point */
/* Déclaration de la fonction chargée de communiquer avec les serveurs de Google */
function geocodeMyAddress(pt){
if(adr != ''){ /* Si une adresse a été fournie */
/* Essai de géolocalisation auprès de Google */
geocoder.getLocations(pt,function(point) {
if(!point) {
/* L'adresse n'a pu être géolocalisée */
alert("! "+adr+" n'existe pas ou n'a pu être géolocalisée ...");
}else if(point['Status']['code'] == 200){
var cache = geocoder.getCache();
for(i in cache)
/* permet de lister le contenu de la variable cache */
GLog.write(i+' : '+cache[i]);
}}
);
}
}
</script>
setCache()
Disponible depuis la version 2.55 de l’Api.
Signature de la méthode setCache : setCache(cache : GGeocodeCache [bientôt en ligne]).
Cette méthode définit un cache côté client. Si cette méthode est invoquée avec un cache définit à null, le système de cache côté client sera désactivé.
La définition d’un nouveau cache aura pour effet de le réinitialiser en supprimant notamment (du cache) les adresses précédemment enregistrées.
Définir le cache de la classe GClientGeocoder
<script type="text/javascript">
var geocoder = new GClientGeocoder();
/* Créé un objet de type GClientGeocoder, prêt à être utilisé. */
geocoder.setCache(null);
/* Désactive le cache côté client */
</script>
setViewport()
Disponible depuis la version 2.82 de l’Api.
Signature de la méthode setViewport : setViewport(bounds : GLatLngBounds).
Cette méthode permet d’indiquer au service de géocodage de Google de privilégier telle ou telle zone définie par l’objet de type GLatLngBounds (zone rectangulaire) passé en paramètre.
Elle peut s’avérer utile lorsque plusieurs points correspondent à l’adresse ou à la ville passée en paramètre et que l’application cherche à renvoyer des informations liées plus à une région qu’à une autre.
Il est important de noter que cette méthode n’est qu’une indication envoyée à Google qui ne sera pas forcément respectée…
Privilégier une zone de recherche
<script type="text/javascript">
Prenons l'exemple de la "rue Jean-Jaurès".
Sans précision quelconque, le service de géocodage de Google
renvoie une dizaine de points (placemarks) différents.
Nous allons tenter d'orienter la recherche sur la Bretagne.
var geocoder = new GClientGeocoder();
/* Créé un objet de type GClientGeocoder, prêt à être utilisé. */
var coinNordOuest = new GLatLng(48.541401, -4.6578613);
var coinSudEst = new GLatLng(47.2168424, -1.5567445);
/* Déclaration des extrémités de la zone géographique (Ploudalmézeau / Nantes). */
geocoder.setViewport(new GLatLngBounds(coinNordOuest, coinSudEst));
/* Application de la zone de recherche à privilégier */
var polygone = new GPolyline([
new GLatLng(coinSudEst.lat(), coinNordOuest.lng()),
new GLatLng(coinSudEst.lat(), coinSudEst.lng()),
new GLatLng(coinNordOuest.lat(), coinSudEst.lng()),
new GLatLng(coinNordOuest.lat(), coinNordOuest.lng()),
new GLatLng(coinSudEst.lat(), coinNordOuest.lng())
], "#ffffff", 3);
/* Création de la zone géographique pour aperçu sur la carte (rectangle blanc) */
map.addOverlay(polygone);
/* ajout du polygone sur la map */
/* Déclaration de la fonction chargée de communiquer avec les serveurs de Google */
function geocodeMyAddress(adr){
if(adr != ''){ /* Si une adresse a été fournie */
/* Essai de géolocalisation auprès de Google */
geocoder.getLatLng(adr,function(point) {
if(!point) {
/* L'adresse n'a pu être géolocalisée */
alert("! "+adr+" n'existe pas ou n\'a pu être géolocalisée ...");
}else{
/* Géolocalisation ok. Un objet de type GPoint est renvoyé,
on récupère les coordonnées */
var a = point.lat();
var b = point.lng();
/* Affichage d'un marker avec infobulle */
var marker = new GMarker(point);
map.addOverlay(marker);
marker.openInfoWindowHtml(CONTENU INFO BULLE);
/* Centrage de la carte sur le point */
map.setCenter(new GLatLng(a,b), 12);
}}
);
}
}
</script>
Résultat obtenu à l’aide de l’indication setViewport
Ici, on observe que le résultat obtenu est bien celui recherché.
Il est bon de préciser à nouveau que cette indication n’est pas toujours respectée.
getViewport()
Disponible depuis la version 2.82 de l’Api.
Signature de la méthode getViewport : getViewport().
Cette méthode retourne un objet de type GLatLngBounds (zone rectangulaire) correspondant à la zone privilégiée pour la recherche d’un point.
setBaseCountryCode()
Disponible depuis la version 2.82 de l’Api.
Signature de la méthode setBaseCountryCode : setBaseCountryCode(countryCode : string).
Cette méthode permet de privilégier la recherche pour un pays donné en fournissant le code pays en paramètre. Par défaut, le pays de recherche sera celui du domaine sur lequel est hébergée votre application Google Map.
La méthode n’est pas sensible à la casse.
Privilégier un pays pour la recherche
<script type="text/javascript">
Par exmple, si l'on recherche "Kennedy", le résultat jugé le plus pertinent se trouve
situé au Pérou parmi une dizaine de points (dont le Mexique).
En précisant le code MX (pour Mexique) pour le pays dans lequel privilégier
la recherche, le résultat renvoyé sera bien situé au Mexique.
var geocoder = new GClientGeocoder();
/* Créé un objet de type GClientGeocoder, prêt à être utilisé. */
geocoder.setBaseCountryCode('MX');
/* Privilégiera la recherche pour le Mexique */
voir la liste des codes pays
</script>
getBaseCountryCode()
Disponible depuis la version 2.82 de l’Api.
Signature de la méthode getBaseCountryCode : getBaseCountryCode().
Cette méthode retourne le code pays privilégié pour la recherche de l’adresse envoyée. Si le code pays n’a pas été renseigné, la méthode renvoie null.
reset()
Disponible depuis la version 2.55 de l’Api.
Signature de la méthode reset : reset().
Cette méthode réinitialise le géocodage en cours. En particulier, cette méthode fait appel à la méthode GGeocodeCache.reset() [bientôt en ligne] sur le cache côté client.
