Capas KML y GeoRSS

KmlLayer representa los elementos KML y GeoRSS en una superposición de mosaicos de Google Maps JavaScript API.

Información general

La Google Maps JavaScript API admite los formatos de datos de KML y GeoRSS para la visualización de información geográfica. Estos formatos de datos aparecen en un mapa con un objeto KmlLayer, cuyo constructor toma la URL de un archivo KML o GeoRSS de acceso público.

La Maps JavaScript API convierte los datos XML geográficos proporcionados en una representación de KML que se muestra en el mapa a través de una superposición de mosaicos de la Maps JavaScript API. Este KML tiene el aspecto (y, en cierta medida, el comportamiento) de elementos de superposiciones de la Maps JavaScript API conocidos. Los elementos KML <Placemark> y GeoRSS point se representan como marcadores. Por ejemplo, los elementos <LineString> se representan como polilíneas y los elementos <Polygon> como polígonos. Asimismo, los elementos <GroundOverlay> se representan como imágenes rectangulares en el mapa. Algo que cabe observar, sin embargo, es que estos objetos no son Markers, Polylines, Polygons ni GroundOverlays de la Google Maps JavaScript API, sino que se representan en un único objeto en el mapa.

Los objetos KmlLayer aparecen en un mapa una vez configurada la propiedad map de estos. Puedes eliminarlos del mapa llamando a setMap() y pasando null. El objeto KmlLayer administra la representación de estos elementos hijos mediante la recuperación automática de funciones correspondientes para los límites determinados del mapa. A medida que cambian los límites, las funciones del viewport actual se representan de manera automática.

Debido a que los componentes dentro de KmlLayer se representan a pedido, la capa te permite administrar fácilmente la representación de miles de marcadores, polilíneas y polígonos. Ten en cuenta que no puedes acceder a estos objetos constituyentes en forma directa, aunque cada uno de ellos proporciona eventos de clic que devuelven datos sobre ellos.

Opciones de capa KML

El constructor KmlLayer() pasa, de manera opcional, varios elementos KmlLayerOptions:

• map especifica el Map en el cual debe representarse el objeto KmlLayer. Puedes ocultar un objeto KmlLayer fijando este valor en null en el método setMap().
• preserveViewport especifica que el mapa no debe ajustarse conforme a los límites del contenido de KmlLayer al mostrar la capa. De manera predeterminada, cuando se muestra una KmlLayer el mapa recibe un ajuste de zoom y se posiciona para mostrar todo el contenido de la capa.
• suppressInfoWindows indica que las funciones seleccionables de KmlLayer no deben activar la visualización de objetos InfoWindow.

A su vez, al representarse KmlLayer, contiene una propiedad metadata invariable que incluye el nombre, la descripción, el fragmento de código y el nombre de la capa dentro de un literal de objeto KmlLayerMetadata. Puedes inspeccionar esta información usando el método getMetadata(). Debido a que para la representación de objetos KmlLayer se necesita comunicación asincrónica con un servidor externo, te convendrá escuchar el evento metadata_changed, el cual indicará que la propiedad se completó.

En el ejemplo siguiente, se construye un objeto KmlLayer a partir del flujo GeoRSS determinado:

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);
}

Ver el ejemplo de GeoRSS

En el ejemplo siguiente, se construye un objeto KmlLayer a partir del flujo KML determinado:

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
  });
}

Ver el ejemplo de KML

Detalles de funciones KML

Debido a que KML puede incluir un gran número de funciones, no puedes acceder a datos de funciones directamente desde el objeto KmlLayer. En contraposición, a medida que se muestran las funciones, se representan de modo que tengan el aspecto de superposiciones de la Maps JavaScript API seleccionables. De manera predeterminada, cuando se hace clic en funciones individuales aparece un objeto InfoWindow que contiene información de <title> y <description> de KML relacionada con la función determinada. A su vez, cuando se hace clic en una función KML se genera un KmlMouseEvent que pasa la siguiente información:

• position indica las coordenadas de latitud y longitud en las cuales debe fijarse el objeto InfoWindow para esta función KML. Esta posición generalmente corresponde a la ubicación seleccionada de polígonos, polilíneas y objetos GroundOverlay, y al verdadero origen de marcadores.
• pixelOffset indica el offset del objeto position de arriba para fijar la “cola” de InfoWindow. En el caso de los objetos poligonales, este offset normalmente es de 0,0, pero en el caso de los marcadores se incluye la altura.
• featureData contiene una estructura JSON de KmlFeatureData.

Aquí se muestra un ejemplo de objeto KmlFeatureData:

{
  author: {
    email: "[e-mail]",
    name: "Mr Nobody",
    uri: "http://example.com"
  },
  description: "description",
  id: "id",
  infoWindowHtml: "html",
  name: "name",
  snippet: "snippet"
}

En el ejemplo siguiente, se muestra texto de <Description> de la función KML dentro de un elemento <div> lateral cuando se hace clic en la función:

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;
  }
}

Ver el ejemplo de KML

Restricciones de tamaño y complejidad para la representación de KML

La Google Maps JavaScript API tiene limitaciones para el tamaño y la complejidad de los archivos KML cargados. A continuación, se ofrece un resumen de los límites actuales.

Nota: Estos límites están sujetos a cambios en cualquier momento.

Tamaño máximo del archivo obtenido (KML sin procesar, GeoRSS sin procesar o KMZ comprimido)

3 MB

Tamaño máximo del archivo KML sin comprimir

10 MB

Cantidad máxima de vínculos de red

10

Cantidad máxima de funciones en todo el documento

1000

Cantidad de capas KML

Existe un límite para la cantidad de capas KML que se pueden mostrar en un solo mapa de Google. Si se supera ese límite, ninguna de ellas aparecerá en el papa y se notificará un error en la consola de JavaScript de tu navegador web. El límite se basa en una combinación de la cantidad de clases KMLLayer creadas y la longitud total de todas las URL usadas para crear esas capas. Cada KMLLayer nuevo que creas consume una parte del límite para la capa y una parte adicional del límite según la longitud de la URL desde la que se cargó el archivo KML. En consecuencia, la cantidad de capas que puedes agregar variará según la aplicación. En promedio, deberás poder cargar entre 10 y 20 capas sin alcanzar el límite. Si alcanzas el límite, usa un acortador de URL (como https://goo.gl) para reducir las URL del KML. También puedes crear un solo archivo KML que consista en NetworkLinks para las URL individuales del KML.

Elementos de KML admitidos

La Google Maps JavaScript API admite los siguientes elementos de KML. El analizador de KML generalmente ignora de forma automática las etiquetas XML que no interpreta.

• Marcas de posición.
• Íconos
• Carpetas.
• HTML descriptivo; reemplazo de entidad a través de <BalloonStyle> y <text>.
• KMZ (KML comprimido, incluidas las imágenes adjuntas).
• Polilíneas y polígonos.
• Estilos para polilíneas y polígonos, incluidos el color, el relleno y la opacidad.
• Vínculos de red para importar datos de forma dinámica
• Superposiciones de suelo superposiciones de pantalla

En la siguiente tabla, se proporcionan detalles completos de los elementos KML admitidos.

Elemento KML	¿Admitido en la API?	Comentario
<address>	no
<AddressDetails>	No
<Alias>	N/D	<Model> no es compatible.
<altitude>	No
<altitudeMode>	No
<atom:author>	Sí
<atom:link>	Sí
<atom:name>	Sí
<BalloonStyle>	Parcialmente	Solo es compatible <text>.
<begin>	N/D	<TimeSpan> no es compatible.
<bgColor>	No
<bottomFov>	N/D	<PhotoOverlay> no es compatible.
<Camera>	No
<Change>	Parcialmente	Solo se admiten cambios de estilo.
<color>	Parcialmente	Incluye #AABBGGRR y #BBGGRR; no admitido en <IconStyle>, <ScreenOverlay> y <GroundOverlay>.
<colorMode>	no
<cookie>	no
<coordinates>	Sí
<Create>	No
<Data>	Sí
<Delete>	No
<description>	Sí	El contenido HTML está permitido, pero se depura para brindar protección contra ataques en navegadores. No se admiten los reemplazos de entidad con la forma $[dataName].
<displayMode>	No
<displayName>	No
<Document>	Parcialmente	De forma implícita, se admiten elementos secundarios. No hay efectos como campos secundarios de otras funciones.
<drawOrder>	no
<east>	Sí
<end>	N/D	<TimeSpan> no es compatible.
<expires>	Sí	Consulta la sección Resumen para obtener información detallada.
<ExtendedData>	Parcialmente	Solo <Data> sin tipo. No se admiten <SimpleData> ni <Schema>, ni reemplazos de entidades con la forma $[dataName].
<extrude>	No
<fill>	Sí
<flyToView>	no
<Folder>	Sí
<geomColor>	no	Obsoleto.
<GeometryCollection>	no	Obsoleto.
<geomScale>	no	Obsoleto.
<gridOrigin>	N/D	<PhotoOverlay> no es compatible.
<GroundOverlay>	Sí	No se puede girar.
<h>	Sí	Obsoleto.
<heading>	Sí
hint	Sí	Se admite target=....
<hotSpot>	Sí
<href>	Sí
<httpQuery>	No
<Icon>	Sí	No se puede girar.
<IconStyle>	Sí
<ImagePyramid>	N/D	<PhotoOverlay> no es compatible.
<innerBoundaryIs>	Sí	Implícitamente, a partir del orden <LinearRing>.
<ItemIcon>	N/D	<ListStyle> no es compatible.
<key>	N/D	No se admite <StyleMap>.
<kml>	Sí
<labelColor>	no	Obsoleto.
<LabelStyle>	No
<latitude>	Sí
<LatLonAltBox>	Sí
<LatLonBox>	Sí
<leftFov>	N/D	<PhotoOverlay> no es compatible.
<LinearRing>	Sí
<LineString>	Sí
<LineStyle>	Sí
<Link>	Sí
<linkDescription>	no
<linkName>	no
<linkSnippet>	no
<listItemType>	N/D	<ListStyle> no es compatible.
<ListStyle>	No
<Location>	N/D	<Model> no es compatible.
<Lod>	Sí
<longitude>	Sí
<LookAt>	No
<maxAltitude>	Sí
<maxFadeExtent>	Sí
<maxHeight>	N/D	<PhotoOverlay> no es compatible.
<maxLodPixels>	Sí
<maxSessionLength>	No
<maxWidth>	N/D	<PhotoOverlay> no es compatible.
<message>	no
<Metadata>	no	Obsoleto.
<minAltitude>	Sí
<minFadeExtent>	Sí
<minLodPixels>	Sí
<minRefreshPeriod>	No	<NetworkLink>
<Model>	No
<MultiGeometry>	Parcialmente	Se representa, pero se muestra como funciones independientes en el panel de la izquierda.
<name>	Sí
<near>	N/D	<PhotoOverlay> no es compatible.
<NetworkLink>	Sí
<NetworkLinkControl>	Parcialmente	<Update> y <expires> se admiten parcialmente. La API ignora la configuración de caducidad en los encabezados de HTTP, pero usa la configuración de caducidad especificada en KML. Ante la ausencia de una configuración de caducidad, o dentro del intervalo de validez, Google Maps puede almacenar en caché datos obtenidos de Internet durante períodos indefinidos. La recuperación de los datos de Internet se puede forzar cambiando el nombre del documento y obteniéndolo a través de una URL diferente, o asegurándote de que el documento contenga la configuración de caducidad correcta.
<north>	Sí
<open>	Sí
<Orientation>	N/D	<Model> no es compatible.
<outerBoundaryIs>	Sí	Implícitamente, a partir del orden <LinearRing>.
<outline>	Sí
<overlayXY>	No
<Pair>	N/D	No se admite <StyleMap>.
<phoneNumber>	no
<PhotoOverlay>	No
<Placemark>	Sí
<Point>	Sí
<Polygon>	Sí
<PolyStyle>	Sí
<range>	Sí
<refreshInterval>	Parcialmente	<Link> únicamente; no en <Icon>.
<refreshMode>	Sí	Los encabezados HTTP no se admiten para el modo “onExpire”. Consulta las notas anteriores sobre <Update> y <expires>.
<refreshVisibility>	No
<Region>	Sí
<ResourceMap>	N/D	<Model> no es compatible.
<rightFov>	N/D	<PhotoOverlay> no es compatible.
<roll>	N/D	<Camera> y <Model> no son compatibles.
<rotation>	no
<rotationXY>	No
<Scale>	N/D	<Model> no es compatible.
<Scale>	no
<Schema>	No
<SchemaData>	No
<ScreenOverlay>	Sí	No se puede girar.
<screenXY>	no
<shape>	N/D	<PhotoOverlay> no es compatible.
<SimpleData>	N/D	<SchemaData> no es compatible.
<SimpleField>	N/D	<Schema> no es compatible.
<size>	Sí
<Snippet>	Sí
<south>	Sí
<state>	N/D	<ListStyle> no es compatible.
<Style>	Sí
<StyleMap>	no	No se admiten efectos de desplazamiento (resalte).
<styleUrl>	N/D	No se admite <StyleMap>.
<targetHref>	Parcialmente	Se admite en <Update>, pero no en <Alias>.
<tessellate>	No
<text>	Sí	No se admite el reemplazo de $[geDirections].
<textColor>	No
<tileSize>	N/D	<PhotoOverlay> no es compatible.
<tilt>	No
<TimeSpan>	No
<TimeStamp>	No
<topFov>	N/D	<PhotoOverlay> no es compatible.
<Update>	Parcialmente	Solo cambios de estilo; se excluyen <Create> y <Delete>.
<Url>	Sí	Obsoleto.
<value>	Sí
<viewBoundScale>	No
<viewFormat>	No
<viewRefreshMode>	Parcialmente	Se admite "onStop".
<viewRefreshTime>	Sí
<ViewVolume>	N/D	<PhotoOverlay> no es compatible.
<visibility>	Parcialmente	Sí en <Folder>; las marcas de posición secundarias heredan su visibilidad.
<w>	Sí	Obsoleto.
<west>	Sí
<when>	N/D	<TimeStamp> no es compatible.
<width>	Sí
<x>	Sí	Obsoleto.
<y>	Sí	Obsoleto.