Vous êtes prêt !

Pour passer à l'étape de développement, accédez à notre documentation pour les développeurs.

Activer Google Maps JavaScript API

Pour commencer, nous allons vous guider à travers la console Google Developers et effectuer deux ou trois petites choses :

  1. Créer ou sélectionner un projet
  2. Activer Google Maps JavaScript API et les services connexes
  3. Créer les clés appropriées
Continuer

Calques KML et GeoRSS

L'objet KmlLayer permet d'effectuer le rendu d'éléments KML et GeoRSS dans une superposition de tuiles Google Maps JavaScript API.

Présentation

Google Maps JavaScript API prend en charge les formats de données KML et GeoRSS pour l'affichage des informations géographiques. Ces formats de données sont affichés sur une carte en utilisant l'objet KmlLayer, dont le constructeur utilise l'URL d'un fichier KML ou GeoRSS accessible publiquement.

Maps JavaScript API convertit les données géographiques XML fournies en une représentation KML qui est affichée sur la carte au moyen d'une superposition de tuiles Maps JavaScript API. Cet élément KML ressemble aux éléments familiers de superposition Maps JavaScript API (et se comporte plus ou moins de la même manière). Les éléments KML <Placemark> et GeoRSS point sont rendus en tant que marqueurs, c'est-à-dire que les éléments <LineString> sont rendus en tant que polylignes et les éléments <Polygon> en tant que polygones. De même, les éléments <GroundOverlay> sont rendus en tant qu'images rectangulaires sur la carte. Plus important encore, toutefois, ces objets ne sont pas des objets Marker, Polyline, Polygon ou GroundOverlay Google Maps JavaScript API. Ils sont rendus en tant qu'objet unique sur la carte.

Les objets KmlLayer apparaissent sur une carte une fois que leur propriété map a été définie. Vous pouvez les supprimer de la carte en appelant la méthode setMap() et en spécifiant la valeur null. L'objet KmlLayer gère le rendu de ces éléments enfants en récupérant automatiquement les composants appropriés pour les limites spécifiées de la carte. Lorsque les limites sont modifiées, les composants de la fenêtre d'affichage ouverte sont rendus automatiquement.

Étant donné que les composants d'un objet KmlLayer sont rendus à la demande, le calque vous permet de facilement gérer le rendu de milliers de marqueurs, polylignes et polygones. Notez que vous ne pouvez pas accéder directement à ces composants, bien qu'ils fournissent chacun des événements de clic renvoyant des données sur ces objets individuels.

Options de calque KML

Le constructeur KmlLayer() permet au besoin de définir un certain nombre d'objets KmlLayerOptions :

  • map spécifie l'objet Map sur lequel effectuer le rendu du calque KmlLayer. Vous pouvez masquer un calque KmlLayer en définissant sa valeur sur null dans la méthode setMap().
  • preserveViewport indique que la carte ne doit pas être ajustée aux limites du contenu du calque KmlLayer lors de l'affichage du calque. Par défaut, lors de l'affichage d'un calque KmlLayer, la carte est agrandie et positionnée pour afficher l'intégralité du contenu du calque.
  • suppressInfoWindows indique que les composants cliquables du calque KmlLayer ne doivent pas déclencher l'affichage d'objets InfoWindow.

Par ailleurs, une fois le calque KmlLayer rendu, il contient une propriété metadata immuable contenant le nom, la description, le fragment et l'auteur du calque dans un littéral objet KmlLayerMetadata. Vous pouvez inspecter ces informations en utilisant la méthode getMetadata(). Étant donné que le rendu des objets KmlLayer nécessite une communication asynchrone vers un serveur externe, vous devez attendre l'événement metadata_changed, qui indique que la propriété a bien été renseignée.

L'exemple suivant construit un objet KmlLayer à partir du flux GeoRSS fourni :

function initMap() {
  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 4,
    center: {lat: 49.496675, lng: -102.65625}
  });

  var georssLayer = new google.maps.KmlLayer({
    url: 'http://api.flickr.com/services/feeds/geo/?g=322338@N20&lang=en-us&format=feed-georss'
  });
  georssLayer.setMap(map);
}
<div id="map"></div>
/* Always set the map height explicitly to define the size of the div
 * element that contains the map. */
#map {
  height: 100%;
}
/* Optional: Makes the sample page fill the window. */
html, body {
  height: 100%;
  margin: 0;
  padding: 0;
}
 <!-- Replace the value of the key parameter with your own API key. -->
<script async defer
src="https://maps.googleapis.com/maps/api/js?key=AIzaSyCkUOdZ5y7hMm0yrcCQoCvLwzdM6M8s5qk&callback=initMap">
</script>
function initMap() {
  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 4,
    center: {lat: 49.496675, lng: -102.65625}
  });

  var georssLayer = new google.maps.KmlLayer({
    url: 'http://api.flickr.com/services/feeds/geo/?g=322338@N20&lang=en-us&format=feed-georss'
  });
  georssLayer.setMap(map);
}

Voir l'exemple GeoRSS

L'exemple suivant construit un objet KmlLayer à partir du flux KML fourni :

function initMap() {
  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 11,
    center: {lat: 41.876, lng: -87.624}
  });

  var ctaLayer = new google.maps.KmlLayer({
    url: 'http://googlemaps.github.io/js-v2-samples/ggeoxml/cta.kml',
    map: map
  });
}
<div id="map"></div>
/* Always set the map height explicitly to define the size of the div
 * element that contains the map. */
#map {
  height: 100%;
}
/* Optional: Makes the sample page fill the window. */
html, body {
  height: 100%;
  margin: 0;
  padding: 0;
}
 <!-- Replace the value of the key parameter with your own API key. -->
<script async defer
src="https://maps.googleapis.com/maps/api/js?key=AIzaSyCkUOdZ5y7hMm0yrcCQoCvLwzdM6M8s5qk&callback=initMap">
</script>
function initMap() {
  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 11,
    center: {lat: 41.876, lng: -87.624}
  });

  var ctaLayer = new google.maps.KmlLayer({
    url: 'http://googlemaps.github.io/js-v2-samples/ggeoxml/cta.kml',
    map: map
  });
}

Voir l'exemple KML

Détails des composants KML

Étant donné que l'élément KML peut inclure un grand nombre de composants, il se peut que vous ne puissiez pas accéder directement aux données des composants à partir de l'objet KmlLayer. À mesure que les composants sont affichés, ils sont rendus de manière à ressembler à des superpositions Maps JavaScript API cliquables. Lorsque vous cliquez sur des composants individuels, cela affiche par défaut une fenêtre InfoWindow contenant les informations KML <title> et <description> sur le composant en question. Par ailleurs, cliquer sur un composant KML génère un événement KmlMouseEvent définissant les informations suivantes :

  • position indique les coordonnées de latitude/longitude sur lesquelles ancrer la fenêtre InfoWindow pour ce composant KML. Cette position est généralement le point géographique cliqué pour les polygones, les polylignes et également les superpositions au sol, mais peut également être la vraie origine des marqueurs.
  • pixelOffset indique le décalage à partir de la position ci-dessus pour ancrer la « queue » de la fenêtre InfoWindow. Pour les objets polygonaux, ce décalage est généralement de 0,0, mais pour les marqueurs, il inclut la hauteur du marqueur.
  • featureData contient une structure JSON d'objets KmlFeatureData.

Un exemple d'objet KmlFeatureData est illustré ci-dessous :

{
  author: {
    email: "nobody@google.com",
    name: "Mr Nobody",
    uri: "http://example.com"
  },
  description: "description",
  id: "id",
  infoWindowHtml: "html",
  name: "name",
  snippet: "snippet"
}

Dans l'exemple suivant, le texte de la <Description> du composant KML est affiché dans une « side <div> » lorsque l'on clique sur le composant :

function initMap() {
  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 12,
    center: {lat: 37.06, lng: -95.68}
  });

  var kmlLayer = new google.maps.KmlLayer({
    url: 'http://googlemaps.github.io/kml-samples/kml/Placemark/placemark.kml',
    suppressInfoWindows: true,
    map: map
  });

  kmlLayer.addListener('click', function(kmlEvent) {
    var text = kmlEvent.featureData.description;
    showInContentWindow(text);
  });

  function showInContentWindow(text) {
    var sidediv = document.getElementById('content-window');
    sidediv.innerHTML = text;
  }
}
<div id="map"></div>
<div id="content-window"></div>
html, body {
  height: 100%;
  margin: 0;
  padding: 0;
}
#map {
  float: left;
  height: 100%;
  width: 79%;
}
#content-window {
  float: left;
  font-family: 'Roboto','sans-serif';
  height: 100%;
  line-height: 30px;
  padding-left: 10px;
  width: 19%;
}
 <!-- Replace the value of the key parameter with your own API key. -->
<script async defer
src="https://maps.googleapis.com/maps/api/js?key=AIzaSyCkUOdZ5y7hMm0yrcCQoCvLwzdM6M8s5qk&callback=initMap">
</script>
function initMap() {
  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 12,
    center: {lat: 37.06, lng: -95.68}
  });

  var kmlLayer = new google.maps.KmlLayer({
    url: 'http://googlemaps.github.io/kml-samples/kml/Placemark/placemark.kml',
    suppressInfoWindows: true,
    map: map
  });

  kmlLayer.addListener('click', function(kmlEvent) {
    var text = kmlEvent.featureData.description;
    showInContentWindow(text);
  });

  function showInContentWindow(text) {
    var sidediv = document.getElementById('content-window');
    sidediv.innerHTML = text;
  }
}

Voir l'exemple KML

Restrictions de taille et de complexité pour le rendu KLM

Google Maps JavaScript API impose certaines restrictions quant à la taille et à la complexité des fichiers KML chargés. Voici un résumé des limites actuelles.

Remarque : Ces limites peuvent à tout moment être modifiées.

Taille maximum du fichier récupéré (KML brut, GeoRSS brut ou KMZ compressé)
3 Mo
Taille maximum du fichier KML décompressé
10 Mo
Nombre maximum de liens réseau
10
Nombre maximum de composants dans tout le document
1 000
Nombre de calques KML
Le nombre de calques KML que l'on peut afficher sur une seule carte est limité. Si vous dépassez cette limite, aucun de vos calques n'apparaîtra sur la carte et une erreur sera signalée dans la console JavaScript de votre navigateur Web. Cette limite est basée sur la combinaison entre le nombre de classes KMLLayer créées et la longueur totale de toutes les URL utilisées pour créer ces calques. Chaque nouvel objet KMLLayer que vous créez occupe une partie des limites du calque, plus une autre partie basée sur la longueur de l'URL à partir de laquelle le fichier KML a été chargé. Le nombre de calques que vous pouvez ajouter dépend donc de l'application. Il est en général possible de charger entre 10 et 20 calques sans atteindre cette limite. Si vous atteignez quand même la limite, utilisez un réducteur d'URL (comme https://goo.gl) pour réduire les URL des fichiers KML. Vous pouvez également ne créer qu'un seul fichier KML constitué de liens NetworkLinks vers des URL de fichier KML individuelles.

Éléments KML pris en charge

Google Maps JavaScript API prend en charge les éléments KML suivants. En général, l'analyseur KML ignore discrètement les balises XML qu'il ne comprend pas.

  • Repères
  • Icônes
  • Dossiers
  • Remplacement d'entité des balises HTML descriptives via <BalloonStyle> et <text>
  • KMZ (fichier KML compressé, y compris les images jointes)
  • Polylignes et polygones
  • Styles des polylignes et des polygones, notamment la couleur, le remplissage et l'opacité
  • Liens réseau pour importer les données de façon dynamique
  • Superpositions au sol et superpositions d'écran

Le tableau suivant fournit les détails complets des éléments KML pris en charge.

Élément KML Pris en charge dans l'API ? Commentaire
<address> non
<AddressDetails> non
<Alias> S/O <Model> non pris en charge
<altitude> non
<altitudeMode> non
<atom:author> oui
<atom:link> oui
<atom:name> oui
<BalloonStyle> partiellement seul <text> est pris en charge
<begin> S/O <TimeSpan> non pris en charge
<bgColor> non
<bottomFov> S/O <PhotoOverlay> non pris en charge
<Camera> non
<Change> partiellement seuls les changements de style sont pris en charge
<color> partiellement inclut #AABBGGRR et #BBGGRR ; non pris en charge dans <IconStyle>, <ScreenOverlay> et <GroundOverlay>
<colorMode> non
<cookie> non
<coordinates> oui
<Create> non
<Data> oui
<Delete> non
<description> oui Le contenu HTML est autorisé, mais il est épuré pour se protéger des attaques entre navigateurs. Les remplacements d'entité du formulaire $[dataName] ne sont pas pris en charge.
<displayMode> non
<displayName> non
<Document> partiellement implicitement, les enfants sont pris en charge ; sans effet en tant qu'enfant d'autres composants
<drawOrder> non
<east> oui
<end> S/O <TimeSpan> non pris en charge
<expires> oui voir la section Résumé pour plus de détails
<ExtendedData> partiellement <Data> non typées uniquement, aucun <SimpleData> ou <Schema> ni aucun remplacement d'entité du formulaire $[dataName] n'est pris en charge.
<extrude> non
<fill> oui
<flyToView> non
<Folder> oui
<geomColor> non obsolète
<GeometryCollection> non obsolète
<geomScale> non obsolète
<gridOrigin> S/O <PhotoOverlay> n'est pas pris en charge
<GroundOverlay> oui ne peut pas pivoter
<h> oui obsolète
<heading> oui
hint oui target=... pris en charge
<hotSpot> oui
<href> oui
<httpQuery> non
<Icon> oui ne peut pas pivoter
<IconStyle> oui
<ImagePyramid> S/O <PhotoOverlay> non pris en charge
<innerBoundaryIs> oui implicitement dans l'ordre <LinearRing>
<ItemIcon> S/O <ListStyle> non pris en charge
<key> S/O <StyleMap> non pris en charge
<kml> oui
<labelColor> non obsolète
<LabelStyle> non
<latitude> oui
<LatLonAltBox> oui
<LatLonBox> oui
<leftFov> S/O <PhotoOverlay> non pris en charge
<LinearRing> oui
<LineString> oui
<LineStyle> oui
<Link> oui
<linkDescription> non
<linkName> non
<linkSnippet> non
<listItemType> S/O <ListStyle> non pris en charge
<ListStyle> non
<Location> S/O <Model> non pris en charge
<Lod> oui
<longitude> oui
<LookAt> non
<maxAltitude> oui
<maxFadeExtent> oui
<maxHeight> S/O <PhotoOverlay> non pris en charge
<maxLodPixels> oui
<maxSessionLength> non
<maxWidth> S/O <PhotoOverlay> non pris en charge
<message> non
<Metadata> non obsolète
<minAltitude> oui
<minFadeExtent> oui
<minLodPixels> oui
<minRefreshPeriod> non <NetworkLink>
<Model> non
<MultiGeometry> partiellement rendu, mais affiché en tant que composant séparé dans le panneau de gauche
<name> oui
<near> S/O <PhotoOverlay> non pris en charge
<NetworkLink> oui  
<NetworkLinkControl> partiellement <Update> et <expires> partiellement pris en charge. L'API ignore les paramètres d'expiration dans les en-têtes HTTP, mais utilise ceux qui sont spécifiés dans le fichier KML. En l'absence de paramètres d'expiration, ou durant l'intervalle de validité, Google Maps peut mettre cache les données récupérées sur Internet pour une durée non spécifiée. Il est possible de forcer une nouvelle récupération des données depuis Internet en renommant le document et en allant le chercher à une autre adresse URL, ou en s'assurant que le document contient des paramètres d'expiration appropriés.
<north> oui
<open> oui
<Orientation> S/O <Model> non pris en charge
<outerBoundaryIs> oui implicitement dans l'ordre <LinearRing>
<outline> oui
<overlayXY> non
<Pair> S/O <StyleMap> non pris en charge
<phoneNumber> non
<PhotoOverlay> non
<Placemark> oui
<Point> oui
<Polygon> oui
<PolyStyle> oui
<range> oui
<refreshInterval> partiellement <Link> uniquement ; pas dans <Icon>
<refreshMode> oui En-têtes HTTP non pris en charge pour le mode « onExpire ». Voir les remarques sur <Update> et <expires> plus haut.
<refreshVisibility> non
<Region> oui
<ResourceMap> S/O <Model> non pris en charge
<rightFov> S/O <PhotoOverlay> non pris en charge
<roll> S/O <Camera> et <Model> non pris en charge
<rotation> non
<rotationXY> non
<Scale> S/O <Model> non pris en charge
<scale> non
<Schema> non
<SchemaData> non
<ScreenOverlay> oui ne peut pas pivoter
<screenXY> non
<shape> S/O <PhotoOverlay> non pris en charge
<SimpleData> S/O <SchemaData> non pris en charge
<SimpleField> S/O <Schema> non pris en charge
<size> oui
<Snippet> oui
<south> oui
<state> S/O <ListStyle> non pris en charge
<Style> oui
<StyleMap> non effets de survol (surbrillance) non pris en charge
<styleUrl> S/O <StyleMap> non pris en charge
<targetHref> partiellement pris en charge dans <Update>, pas dans <Alias>
<tessellate> non
<text> oui remplacement de $[geDirections] non pris en charge
<textColor> non
<tileSize> S/O <PhotoOverlay> non pris en charge
<tilt> non
<TimeSpan> non
<TimeStamp> non
<topFov> S/O <PhotoOverlay> non pris en charge
<Update> partiellement changements de style uniquement, pas <Create> ni <Delete>
<Url> oui obsolète
<value> oui
<viewBoundScale> non
<viewFormat> non
<viewRefreshMode> partiellement « onStop » pris en charge
<viewRefreshTime> oui
<ViewVolume> S/O <PhotoOverlay> non pris en charge
<visibility> partiellement oui sur <Folder> - les repères enfants héritent de leur visibilité
<w> oui obsolète
<west> oui
<when> S/O <TimeStamp> non pris en charge
<width> oui
<x> oui obsolète
<y> oui obsolète

Envoyer des commentaires concernant…

Google Maps JavaScript API
Google Maps JavaScript API
Besoin d'aide ? Consultez notre page d'assistance.