KML- und GeoRSS-Ebenen

Plattform auswählen: Android iOS JavaScript

KmlLayer rendert KML- und GeoRSS-Elemente in ein Maps JavaScript API-Kachel-Overlay.

Übersicht

Die Maps JavaScript API unterstützt die KML- und GeoRSS-Datenformate zum Anzeigen geografischer Informationen. Diese Datenformate werden auf der Karte mithilfe eines KmlLayer-Objekts dargestellt, für dessen Konstruktor die URL einer öffentlich verfügbaren KML- oder GeoRSS-Datei angegeben wird.

Hinweis: Die Klasse KmlLayer, über die KML-Overlays in der Maps JavaScript API generiert werden, verwendet einen von Google gehosteten Dienst, um KML-Dateien zum Rendern abzurufen und zu parsen. Daher können KML-Dateien nur angezeigt werden, wenn sie unter einer öffentlich zugänglichen URL gehostet werden, für deren Zugriff keine Authentifizierung erforderlich ist.

Wenn Sie auf private Dateien zugreifen, Caches detailgenau kontrollieren oder den Darstellungsbereich des Browsers als Abfrageparameter an ein Geoinformationsystem senden müssen, sollten Sie Data-Ebenen anstelle von KmlLayer verwenden. Dadurch werden die Browser Ihrer Nutzer angewiesen, Ressourcen direkt von Ihrem Webserver anzufordern.

Die Maps JavaScript API wandelt die bereitgestellten geografischen XML-Daten in eine KML-Darstellung um, die mithilfe eines Maps JavaScript API-Kachel-Overlays auf der Karte angezeigt wird. Die KML-Darstellung sieht wie bekannte Overlay-Elemente der Maps JavaScript API aus und verhält sich auch ähnlich. KML-<Placemark>- und GeoRSS-point-Elemente werden als Markierungen gerendert, <LineString>-Elemente z. B. als Polylinien und <Polygon>-Elemente als Polygone. In ähnlicher Weise werden <GroundOverlay>-Elemente als rechteckige Bilder auf der Karte gerendert. Diese Objekte sind jedoch keine Markers-, Polylines-, Polygons- oder GroundOverlays-Elemente der Maps JavaScript API. Sie werden stattdessen als einzelnes Objekt auf der Karte gerendert.

KmlLayer-Objekte werden auf einer Karte dargestellt, sobald ihre map-Eigenschaft festgelegt wurde. Sie können sie von der Karte entfernen, indem Sie setMap() aufrufen und dabei null übergeben. Das KmlLayer-Objekt verwaltet das Rendern dieser untergeordneten Elemente, indem es automatisch die passenden Features für die gegebenen Grenzen der Karte abruft. Wenn sich die Grenzen ändern, werden die Features im aktuellen Darstellungsbereich automatisch gerendert.

Da die Komponenten innerhalb einer KmlLayer auf Anfrage gerendert werden, können Sie mit der Ebene ganz einfach das Rendern Tausender Markierungen, Polylinien und Polygone verwalten. Sie können nicht direkt auf die zugehörigen Objekte zugreifen. Stattdessen stellen sie Klickereignisse bereit, die Daten zu den einzelnen Objekten zurückgeben.

Optionen für KML-Ebenen

Der KmlLayer()-Konstruktor gibt optional eine Reihe von KmlLayerOptions weiter:

  • map definiert die Map, auf der die KmlLayer gerendert werden soll. Sie können eine KmlLayer ausblenden, indem Sie in der setMap()-Methode null für diesen Wert festlegen.
  • preserveViewport gibt an, dass die Karte nicht an die Grenzen der KmlLayer-Inhalte angepasst werden soll, wenn die Ebene angezeigt wird. Beim Anzeigen einer KmlLayer wird die Karte standardmäßig so gezoomt und positioniert, dass alle Inhalte der Ebene angezeigt werden.
  • suppressInfoWindows gibt an, dass anklickbare Features innerhalb der KmlLayer nicht die Anzeige von InfoWindow-Objekten auslösen sollen.

Sobald die KmlLayer gerendert ist, enthält sie außerdem eine unveränderliche metadata-Eigenschaft, die den Namen, die Beschreibung, das Snippet und den Autor der Ebene in einem KmlLayerMetadata-Objektliteral enthält. Sie können diese Informationen mithilfe der getMetadata()-Methode einsehen. Da für das Rendern von KmlLayer-Objekten eine asynchrone Kommunikation mit einem externen Server erforderlich ist, sollten Sie das metadata_changed-Ereignis beobachten. Es zeigt an, dass ein Wert für die Eigenschaft gesetzt wurde.

Im folgenden Beispiel wird eine KmlLayer aus dem angegebenen GeoRSS-Feed erstellt:

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

Beispiel ansehen

Im folgenden Beispiel wird eine KmlLayer aus dem angegebenen KML-Feed erstellt:

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: 'https://googlearchive.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
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: 'https://googlearchive.github.io/js-v2-samples/ggeoxml/cta.kml',
    map: map
  });
}

Beispiel ansehen

Details zu KML-Features

KML kann sehr viele Features enthalten. Daher ist es nicht möglich, direkt über das KmlLayer-Objekt auf die Featuredaten zuzugreifen. Werden Features angezeigt, werden sie stattdessen als anklickbare Maps JavaScript API-Overlays gerendert. Wenn ein Feature angeklickt wird, wird standardmäßig ein InfoWindow mit KML-<title> und -<description> des jeweiligen Features eingeblendet. Außerdem wird ein KmlMouseEvent generiert, das folgende Informationen übergibt:

  • position gibt die Breiten- und Längengradkoordinaten an, bei denen das InfoWindow für dieses KML-Feature verankert werden soll. Bei Polygonen, Polylinien und Boden-Overlays ist das in der Regel die Klickposition, bei Markierungen jedoch der tatsächliche Ursprung.
  • pixelOffset gibt die Abweichung zur position oben an, an der die Sprechblasenspitze des InfoWindow verankert werden soll. Bei Polygonobjekten ist das in der Regel 0,0, bei Markierungen enthält sie jedoch die Höhe der Markierung.
  • featureData enthält eine JSON-Struktur mit KmlFeatureData.

Hier ist ein Beispiel für ein KmlFeatureData-Objekt:

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

Mit folgendem Beispiel wird beim Anklicken eines KML-Features der entsprechende <Description>-Text in einem seitlichen <div>-Bereich angezeigt:

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: 425px;
  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
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;
  }
}

Beispiel ansehen

Größen- und Komplexitätsbeschränkungen für das KML-Rendering

Für die Maps JavaScript API gelten Einschränkungen hinsichtlich der Größe und Komplexität von geladenen KML-Dateien. Hier ist eine Übersicht über die aktuellen Limits:

Hinweis: Diese Limits können sich jederzeit ändern.

Maximale Größe für abgerufene Dateien (RAW-KML-, RAW-GeoRSS- oder komprimierte KMZ-Datei)
3 MB
Maximale Größe für nicht komprimierte KML-Dateien
10 MB
Maximale Größe für nicht komprimierte Bilddateien in KMZ-Dateien
500 KB pro Datei
Maximale Anzahl der Netzwerk-Links
10
Maximale Anzahl von Features im Dokument
1.000
Anzahl der KML-Ebenen
Es gibt ein Limit für die Anzahl der KML-Ebenen, die auf einer Google-Karte angezeigt werden können. Wenn Sie das Limit überschreiten, werden keine Ihrer Ebenen auf der Karte angezeigt und es wird ein Fehler in der JavaScript-Konsole Ihres Webbrowsers ausgegeben. Das Limit beruht auf einer Kombination aus der Anzahl der erstellten KmlLayer-Klassen und der Gesamtlänge aller URLs, die zum Erstellen dieser Ebenen verwendet wurden. Jede neu erstellte KmlLayer beansprucht einen Teil des Limits für die Ebene sowie einen weiteren Teil, der sich nach der Länge der URL richtet, von der die KML-Datei geladen wurde. Daher kann sich die Anzahl der Ebenen, die Sie hinzufügen können, je nach Anwendung variieren. Sie sollten durchschnittlich 10 bis 20 Ebenen laden können, ohne das Limit zu überschreiten. Falls Sie es doch erreichen, können Sie die KML-URLs mit einem Kurz-URL-Dienst verkürzen. Alternativ haben Sie die Möglichkeit, eine einzelne KML-Datei mit Netzwerk-Links zu den einzelnen KML-URLs zu erstellen.

Überlegungen zu Leistung und Caching

Die Google-Server speichern KML-Dateien vorübergehend im Cache, um Ihre Server zu entlasten. Dadurch verbessert sich auch die Leistung für Ihre Nutzer, da eine speichereffiziente Darstellung der entsprechenden Segmente Ihrer KML-Datei angezeigt wird, wenn sie die Karte anklicken, verschieben und zoomen.

Für optimale Leistung empfehlen wir Folgendes:

  • Verwenden Sie in KML ein geeignetes <expires>-Tag.

    KmlLayer verwendet keine HTTP-Header, um zu entscheiden, wie KML-Dateien im Cache gespeichert werden sollen.
  • Lassen Sie Dateien nicht zur Zeit der Anfrage dynamisch generieren.

    Generieren Sie die Dateien stattdessen, bevor sie benötigt werden, und stellen Sie sie statisch bereit. Wenn die Übertragung der KML-Datei durch Ihren Server zu lange dauert, wird die KmlLayer möglicherweise nicht angezeigt.
  • Versuchen Sie nicht, Caches zu umgehen, es sei denn, Sie sind sicher, dass Ihre Datei aktualisiert wurde.

    Wenn Sie Caches immer umgehen, indem Sie z. B. eine Zufallszahl oder die Uhrzeit des Nutzers als Abfrageparameter anhängen, können Ihre Server leicht überlastet werden, wenn Ihre Website plötzlich stark frequentiert wird und Sie große KML-Dateien bereitstellen.

    Es kann auch dazu führen, dass der Cache Nutzern veraltete Daten liefert, wenn die Uhr des Nutzers falsch eingestellt ist und das <expires>-Tag nicht korrekt gesetzt wurde.

    Veröffentlichen Sie stattdessen aktualisierte statische Dateien mit einer neuen, eindeutigen Überarbeitungsnummer und verwenden Sie serverseitigen Code, um die an die KmlLayer übergebene URL dynamisch mit der aktuellen Version zu aktualisieren.
  • KML-Dateien sollten höchstens einmal pro Minute aktualisiert werden.

    Wenn alle Dateien zusammen mehr als 1 MB groß sind (unkomprimiert), sollten Änderungen auf einmal alle 5 Minuten begrenzt werden.
  • Bei Nutzung eines Geoinformationsystems sollten Sie keine Abfrageparameter verwenden, um den Darstellungsbereich von Ebenen zu begrenzen.

    Stattdessen können Sie den Darstellungsbereich der Karte mit dem Ereignis bounds_changed einschränken. Nutzer erhalten dann nur Features, die automatisch angezeigt werden können.

    Wenn Ihr Geoinformationsystem eine große Menge an Daten enthält, sollten Sie stattdessen Data-Ebenen verwenden.
  • Wenn Sie ein Geoinformationsystem verwenden, sollten Sie mehrere KmlLayer für jede Gruppe von Features verwenden, die Nutzer ein- und ausblenden können sollen, und keine einzelne KmlLayer mit unterschiedlichen Abfrageparametern.
  • Verwenden Sie komprimierte KMZ-Dateien, um die Dateigröße zu verringern.
  • Wenn Sie Google Cloud Storage oder eine andere Cloud-Speicherlösung nutzen, verwenden Sie möglichst keine Features wie signierte URLs oder temporäre Tokens für die Zugriffssteuerung. Sie könnten das Caching ungewollt verhindern.
  • Verringern Sie die Genauigkeit aller Punkte auf eine ausreichende Genauigkeit.
  • Führen Sie die Geometrie ähnlicher Features, wie z. B. Polygone und Polylinien, zusammen und vereinfachen Sie sie.
  • Entfernen Sie alle Elemente oder Bildressourcen, die nicht verwendet werden.
  • Entfernen Sie alle nicht unterstützten Elemente.

Wenn Sie auf private Daten zugreifen, das Caching verhindern oder den Darstellungsbereich des Browsers als Abfrageparameter an ein Geoinformationsystem senden müssen, sollten Sie Data-Ebenen anstelle von KmlLayer verwenden. Dadurch werden die Browser Ihrer Nutzer angewiesen, Ressourcen direkt von Ihrem Webserver anzufordern.

Unterstützte KML-Elemente

Die Maps JavaScript API unterstützt die folgenden KML-Elemente. In der Regel ignoriert der KML-Parser XML-Tags, die er nicht parsen kann, ohne Meldung.

  • Ortsmarkierungen
  • Symbole
  • Ordner
  • HTML-Beschreibungen: Ersetzen von Entitäten über <BalloonStyle> und <text>
  • KMZ (komprimierter KML-Code, einschließlich angefügte Bilder)
  • Polylinien und Polygone
  • Stile für Polylinien und Polygone, einschließlich Farbe, Füllung und Deckkraft
  • Netzwerk-Links für den dynamischen Import von Daten
  • Boden- und Bildschirm-Overlays

Die folgende Tabelle enthält alle Details zu den unterstützten KML-Elementen.

KML-Element In der API unterstützt? Anmerkung
<address> Nein
<AddressDetails> Nein
<Alias> <Model> wird nicht unterstützt.
<altitude> Nein
<altitudeMode> Nein
<atom:author> Ja
<atom:link> Ja
<atom:name> Ja
<BalloonStyle> Teilweise Nur <text> wird unterstützt.
<begin> <TimeSpan> wird nicht unterstützt.
<bgColor> Nein
<bottomFov> <PhotoOverlay> wird nicht unterstützt.
<Camera> Nein
<Change> Teilweise Nur Formatänderungen werden unterstützt.
<color> Teilweise Umfasst #AABBGGRR und #BBGGRR; nicht unterstützt in <IconStyle>, <ScreenOverlay> und <GroundOverlay>.
<colorMode> Nein
<cookie> Nein
<coordinates> Ja
<Create> Nein
<Data> Ja
<Delete> Nein
<description> Ja HTML-Inhalte sind zulässig, werden jedoch bereinigt, um vor browserübergreifenden Angriffen zu schützen. Entitätsersetzungen im Format $[dataName] werden nicht unterstützt.
<displayMode> Nein
<displayName> Nein
<Document> Teilweise Implizit, untergeordnete Elemente werden unterstützt; keine Auswirkung als untergeordnetes Element anderer Features.
<drawOrder> Nein
<east> Ja
<end> <TimeSpan> wird nicht unterstützt.
<expires> Ja Weitere Informationen finden Sie im Abschnitt „Übersicht“.
<ExtendedData> Teilweise Nur nicht typisierte <Data>; <SimpleData> oder <Schema> und Entitätsersetzungen im Format $[dataName] werden nicht unterstützt.
<extrude> Nein
<fill> Ja
<flyToView> Nein
<Folder> Ja
<geomColor> Nein Verworfen
<GeometryCollection> Nein Verworfen
<geomScale> Nein Verworfen
<gridOrigin> <PhotoOverlay> wird nicht unterstützt.
<GroundOverlay> Ja Kann nicht gedreht werden.
<h> Ja Verworfen
<heading> Ja
hint Ja target=... wird unterstützt.
<hotSpot> Ja
<href> Ja
<httpQuery> Nein
<Icon> Ja Kann nicht gedreht werden.
<IconStyle> Ja
<ImagePyramid> <PhotoOverlay> wird nicht unterstützt.
<innerBoundaryIs> Ja Implizit aus <LinearRing>-Reihenfolge
<ItemIcon> <ListStyle> wird nicht unterstützt.
<key> <StyleMap> wird nicht unterstützt.
<kml> Ja
<labelColor> Nein Verworfen
<LabelStyle> Nein
<latitude> Ja
<LatLonAltBox> Ja
<LatLonBox> Ja
<leftFov> <PhotoOverlay> wird nicht unterstützt.
<LinearRing> Ja
<LineString> Ja
<LineStyle> Ja
<Link> Ja
<linkDescription> Nein
<linkName> Nein
<linkSnippet> Nein
<listItemType> <ListStyle> wird nicht unterstützt.
<ListStyle> Nein
<Location> <Model> wird nicht unterstützt.
<Lod> Ja
<longitude> Ja
<LookAt> Nein
<maxAltitude> Ja
<maxFadeExtent> Ja
<maxHeight> <PhotoOverlay> wird nicht unterstützt.
<maxLodPixels> Ja
<maxSessionLength> Nein
<maxWidth> <PhotoOverlay> wird nicht unterstützt.
<message> Nein
<Metadata> Nein Verworfen
<minAltitude> Ja
<minFadeExtent> Ja
<minLodPixels> Ja
<minRefreshPeriod> Nein <NetworkLink>
<Model> Nein
<MultiGeometry> Teilweise Wird gerendert, aber als separates Feature links auf der Seite angezeigt.
<name> Ja
<near> <PhotoOverlay> wird nicht unterstützt.
<NetworkLink> Ja  
<NetworkLinkControl> Teilweise <Update> und <expires> werden teilweise unterstützt. Die API ignoriert die Ablaufeinstellungen in den HTTP-Headern, berücksichtigt aber die in der KML-Datei. Bei fehlenden Ablaufeinstellungen oder innerhalb des zeitlichen Gültigkeitsintervalls kann Google Maps die aus dem Internet abgerufenen Daten für eine unbestimmte Dauer im Cache speichern. Das erneute Abrufen der Daten aus dem Internet kann erzwungen werden, indem das Dokument umbenannt und der Abruf unter einer anderen URL erfolgt oder indem Sie sicherstellen, dass das Dokument geeignete Ablaufeinstellungen enthält.
<north> Ja
<open> Ja
<Orientation> <Model> wird nicht unterstützt.
<outerBoundaryIs> Ja Implizit aus <LinearRing>-Reihenfolge
<outline> Ja
<overlayXY> Nein
<Pair> <StyleMap> wird nicht unterstützt.
<phoneNumber> Nein
<PhotoOverlay> Nein
<Placemark> Ja
<Point> Ja
<Polygon> Ja
<PolyStyle> Ja
<range> Ja
<refreshInterval> Teilweise Nur <Link>; nicht in <Symbol>.
<refreshMode> Ja HTTP-Header werden für den Modus „onExpire“ nicht unterstützt. Weitere Informationen finden Sie oben unter <Update> und <expires>.
<refreshVisibility> Nein
<Region> Ja
<ResourceMap> <Model> wird nicht unterstützt.
<rightFov> <PhotoOverlay> wird nicht unterstützt.
<roll> <Camera> und <Model> werden nicht unterstützt.
<rotation> Nein
<rotationXY> Nein
<Scale> <Model> wird nicht unterstützt.
<scale> Nein
<Schema> Nein
<SchemaData> Nein
<ScreenOverlay> Ja Kann nicht gedreht werden.
<screenXY> Nein
<shape> <PhotoOverlay> wird nicht unterstützt.
<SimpleData> <SchemaData> wird nicht unterstützt.
<SimpleField> <Schema> wird nicht unterstützt.
<size> Ja
<Snippet> Ja
<south> Ja
<state> <ListStyle> wird nicht unterstützt.
<Style> Ja
<StyleMap> Nein Mouseover-Effekte (Hervorhebungen) werden nicht unterstützt.
<styleUrl> <StyleMap> wird nicht unterstützt.
<targetHref> Teilweise Unterstützt in <Update>, nicht in <Alias>.
<tessellate> Nein
<text> Ja Ersetzen von $[geDirections] wird nicht unterstützt.
<textColor> Nein
<tileSize> <PhotoOverlay> wird nicht unterstützt.
<tilt> Nein
<TimeSpan> Nein
<TimeStamp> Nein
<topFov> <PhotoOverlay> wird nicht unterstützt.
<Update> Teilweise Nur Stiländerungen, nicht <Create> oder <Delete>.
<Url> Ja Verworfen
<value> Ja
<viewBoundScale> Nein
<viewFormat> Nein
<viewRefreshMode> Teilweise „onStop“ wird unterstützt.
<viewRefreshTime> Ja
<ViewVolume> <PhotoOverlay> wird nicht unterstützt.
<visibility> Teilweise Ja für <Folder> – die Sichtbarkeit wird für untergeordnete Ortsmarkierungen übernommen.
<w> Ja Verworfen
<west> Ja
<when> <TimeStamp> wird nicht unterstützt.
<width> Ja
<x> Ja Verworfen
<y> Ja Verworfen