Layer KML dan GeoRSS

KmlLayer merender elemen KML dan GeoRSS menjadi overlay petak Google Maps JavaScript API.

Ringkasan

Google Maps JavaScript API mendukung format data KML dan GeoRSS untuk menampilkan informasi geografis. Format data akan ditampilkan pada peta menggunakan objek KmlLayer, yang konstruktornya mengambil URL dari file KML atau GeoRSS yang bisa diakses oleh umum.

Maps JavaScript API mengonversi data XML geografis yang disediakan menjadi representasi KML yang ditampilkan pada peta menggunakan overlay petak Maps JavaScript API. KML ini terlihat (dan berperilaku) seperti elemen overlay Maps JavaScript API yang sudah lama dikenal. Elemen <Placemark> KML dan elemen point GeoRSS dirender sebagai marker, misalnya, elemen <LineString> dirender sebagai polyline dan elemen <Polygon> dirender sebagai poligon. Demikian pula, elemen <GroundOverlay> dirender sebagai gambar persegi panjang pada peta. Akan tetapi, yang penting, objek-objek ini bukan Markers, Polylines, Polygons atau GroundOverlays Google Maps JavaScript API; melainkan, objek-objek tersebut dirender menjadi satu objek pada peta.

Objek KmlLayer muncul pada peta setelah properti map disetel. Anda bisa membuangnya dari peta dengan memanggil setMap() dan meneruskan null. Objek KmlLayer mengelola rendering elemen-elemen anak ini dengan secara otomatis mengambil fitur yang sesuai untuk batas peta yang diberikan. Saat batasnya berubah, fitur di viewport saat ini secara otomatis akan dirender.

Karena komponen dalam KmlLayer dirender berdasarkan permintaan, layer memudahkan Anda mengelola hasil rendering ribuan marker, polyline, dan poligon. Perhatikan, Anda tidak bisa mengakses objek konstituen secara langsung, meskipun masing-masing memberikan kejadian klik yang mengembalikan data pada masing-masing objek tersebut.

Opsi Layer KML

Konstruktor KmlLayer()secara opsional meneruskan sejumlah KmlLayerOptions:

• map menetapkan Map yang akan digunakan merender KmlLayer. Anda bisa menyembunyikan KmlLayer dengan menyetel nilainya ke null dalam metode setMap().
• preserveViewport menetapkan bahwa peta tidak boleh disesuaikan ke batas materi KmlLayer saat menampilkan layer. Secara default, saat menampilkan KmlLayer, peta diperbesar dan diposisikan untuk menampilkan keseluruhan materi layer.
• suppressInfoWindows menunjukkan fitur yang bisa diklik dalam KmlLayer tidak boleh memicu ditampilkannya objek InfoWindow.

Di samping itu, setelah KmlLayer dirender, maka akan memuat properti metadata tetap yang berisi nama layer, keterangan, cuplikan dan penulis dalam literal objek KmlLayerMetadata. Anda bisa memeriksa informasi ini dengan metode getMetadata(). Karena rendering objek KmlLayer memerlukan komunikasi asinkron ke server eksternal, maka Anda perlu memantau kejadian metadata_changed, yang akan menunjukkan properti telah diisi.

Contoh berikut membuat sebuah KmlLayer dari umpan GeoRSS yang diberikan:

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

Tampilkan contoh GeoRSS

Contoh berikut membuat sebuah KmlLayer dari umpan KML yang diberikan:

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

Tampilkan contoh KML

Detail fitur KML

Karena KML mungkin menyertakan fitur dalam jumlah besar, Anda tidak boleh mengakses data fitur dari objek KmlLayer secara langsung. Melainkan, saat fitur ditampilkan, fitur akan dirender agar terlihat seperti overlay Maps JavaScript API yang bisa diklik. Mengeklik fitur individual, secara default, akan memunculkan InfoWindow berisi informasi <title> dan <description> KML mengenai fitur yang diberikan. Selain itu, mengeklik fitur KML akan menghasilkan KmlMouseEvent, yang meneruskan informasi berikut:

• position menunjukkan koordinat garis lintang/garis bujur yang digunakan untuk menautkan InfoWindow bagi fitur KML ini. Posisi ini biasanya adalah lokasi klik untuk poligon, polyline, dan GroundOverlays, namun merupakan asal sesungguhnya untuk marker.
• pixelOffset menunjukkan offset dari position di atas untuk menambatkan “ekor” InfoWindow. Untuk objek poligonal, offset ini biasanya 0,0 namun untuk marker berisi ketinggian marker.
• featureData berisi struktur JSON dari KmlFeatureData.

Contoh objek KmlFeatureData ditampilkan di bawah ini:

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

Contoh berikut menampilkan teks <Description> fitur KML dalam sisi <div> bila fitur diklik:

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

Tampilkan contoh KML

Batasan ukuran dan kompleksitas untuk rendering KML

Google Maps JavaScript API memiliki batasan terhadap ukuran dan kompleksitas file KML yang dimuat. Di bawah ini adalah rangkuman batas yang saat ini berlaku.

Catatan: Batas ini bisa berubah kapan saja.

Ukuran file maksimum yang bisa diambil (KML mentah, GeoRSS mentah, atau KMZ yang dikompresi)

3MB

Ukuran maksimum file KML yang tidak dikompresi

10 MB

Jumlah maksimum tautan jaringan

10

Jumlah maksimum total fitur seluruh dokumen

1.000

Jumlah layer KML

Terdapat batas jumlah Layer KML yang bisa ditampilkan pada satu Peta Google. Jika Anda melebihi batas ini, tidak satu pun layer Anda yang akan muncul pada peta dan sebuah kesalahan akan dilaporkan di Konsol JavaScript browser web Anda. Batas didasarkan pada kombinasi jumlah kelas KMLLayer yang dibuat dan total panjang semua URL yang digunakan untuk membuat layer tersebut. Setiap KMLLayer baru yang Anda buat akan memakan bagian batas untuk layer dan bagian lain dari batas tergantung pada panjang URL asal file KML dimuat. Dengan demikian, jumlah layer yang bisa Anda tambahkan berbeda dari satu aplikasi dengan yang lain; rata-rata, Anda seharusnya bisa memuat antara 10 sampai 20 layer tanpa mencapai batas. Jika Anda masih mencapai batas, gunakan pemendek URL (seperti https://goo.gl) untuk memendekkan URL KML. Atau, buat file KML tunggal yang berisi NetworkLinks ke masing-masing URL KML.

Elemen KML yang didukung

Google Maps JavaScript API mendukung elemen KML berikut. Parser KML umumnya mengabaikan tag XML yang tidak dipahaminya secara diam-diam.

• Placemark
• Ikon
• Folder
• HTML deskriptif—Penggantian entitas melalui <BalloonStyle> dan <text>
• KMZ (KML yang dikompresi, termasuk gambar yang dilampirkan)
• Polyline dan poligon
• Gaya untuk polyline dan poligon, termasuk warna, isian, dan opasitas
• Tautan jaringan untuk mengimpor data secara dinamis
• Overlay bumi dan overlay layar

Tabel berikut berisi detail penuh elemen KML yang didukung.

Elemen KML	Didukung di API?	Komentar
<address>	tidak
<AddressDetails>	tidak
<Alias>	N/A	<Model> tidak didukung
<altitude>	tidak
<altitudeMode>	tidak
<atom:author>	ya
<atom:link>	ya
<atom:name>	ya
<BalloonStyle>	sebagian	hanya <text> yang didukung
<begin>	N/A	<TimeSpan> tidak didukung
<bgColor>	tidak
<bottomFov>	N/A	<PhotoOverlay> tidak didukung
<Camera>	tidak
<Change>	sebagian	hanya perubahan gaya yang didukung
<color>	sebagian	menyertakan #AABBGGRR dan #BBGGRR; tidak didukung di <IconStyle>, <ScreenOverlay>, dan <GroundOverlay>
<colorMode>	tidak
<cookie>	tidak
<coordinates>	ya
<Create>	tidak
<Data>	ya
<Delete>	tidak
<description>	ya	Materi HTML diizinkan tetapi disanitasi untuk melindungi dari serangan lintas browser. Penggantian entitas bentuk $[dataName] tidak didukung.
<displayMode>	tidak
<displayName>	tidak
<Document>	sebagian	secara implisit, turunan didukung; tidak ada dampak sebagai turunan Fitur lain
<drawOrder>	tidak
<east>	ya
<end>	N/A	<TimeSpan> tidak didukung
<expires>	ya	lihat bagian Rangkuman untuk detailnya
<ExtendedData>	sebagian	hanya <Data> tidak bertipe, bukan <SimpleData> atau <Schema> dan penggantian entitas bentuk $[dataName] tidak didukung.
<extrude>	tidak
<fill>	ya
<flyToView>	tidak
<Folder>	ya
<geomColor>	tidak	tidak digunakan lagi
<GeometryCollection>	tidak	tidak digunakan lagi
<geomScale>	tidak	tidak digunakan lagi
<gridOrigin>	N/A	<PhotoOverlay> tidak didukung
<GroundOverlay>	ya	tidak bisa diputar
<h>	ya	tidak digunakan lagi
<heading>	ya
petunjuk	ya	target=... didukung
<hotSpot>	ya
<href>	ya
<httpQuery>	tidak
<Icon>	ya	tidak bisa diputar
<IconStyle>	ya
<ImagePyramid>	N/A	<PhotoOverlay> tidak didukung
<innerBoundaryIs>	ya	secara implisit dari perintah <LinearRing>
<ItemIcon>	N/A	<ListStyle> tidak didukung
<key>	N/A	<StyleMap> tidak didukung
<kml>	ya
<labelColor>	tidak	tidak digunakan lagi
<LabelStyle>	tidak
<latitude>	ya
<LatLonAltBox>	ya
<LatLonBox>	ya
<leftFov>	N/A	<PhotoOverlay> tidak didukung
<LinearRing>	ya
<LineString>	ya
<LineStyle>	ya
<Link>	ya
<linkDescription>	tidak
<linkName>	tidak
<linkSnippet>	tidak
<listItemType>	N/A	<ListStyle> tidak didukung
<ListStyle>	tidak
<Location>	N/A	<Model> tidak didukung
<Lod>	ya
<longitude>	ya
<LookAt>	tidak
<maxAltitude>	ya
<maxFadeExtent>	ya
<maxHeight>	N/A	<PhotoOverlay> tidak didukung
<maxLodPixels>	ya
<maxSessionLength>	tidak
<maxWidth>	N/A	<PhotoOverlay> tidak didukung
<message>	tidak
<Metadata>	tidak	tidak digunakan lagi
<minAltitude>	ya
<minFadeExtent>	ya
<minLodPixels>	ya
<minRefreshPeriod>	tidak	<NetworkLink>
<Model>	tidak
<MultiGeometry>	sebagian	dirender, tetapi ditampilkan sebagai fitur terpisah di panel sisi kiri
<name>	ya
<near>	N/A	<PhotoOverlay> tidak didukung
<NetworkLink>	ya
<NetworkLinkControl>	sebagian	<Update> dan <expires> didukung sebagian. API mengabaikan setelan habis masa berlaku di header HTTP tetapi tidak menggunakan setelan habis masa berlaku yang ditetapkan di KML. Dengan tidak adanya setelan habis masa berlaku, atau dalam interval validitas waktu, Google Maps dapat membuat cache data yang diambil dari Internet untuk durasi yang tidak ditetapkan. Pengambilan data ulang dari Internet bisa dipaksakan dengan mengganti nama dokumen dan mengambilnya dengan URL yang berbeda, atau dengan memastikan dokumen berisi setelan habis masa berlaku yang sesuai.
<north>	ya
<open>	ya
<Orientation>	N/A	<Model> tidak didukung
<outerBoundaryIs>	ya	secara implisit dari perintah <LinearRing>
<outline>	ya
<overlayXY>	tidak
<Pair>	N/A	<StyleMap> tidak didukung
<phoneNumber>	tidak
<PhotoOverlay>	tidak
<Placemark>	ya
<Point>	ya
<Polygon>	ya
<PolyStyle>	ya
<range>	ya
<refreshInterval>	sebagian	<Link> saja; tidak berada dalam <Icon>
<refreshMode>	ya	Header HTTP tidak didukung untuk mode "onExpire". Lihat catatan tentang <Update> dan <expires> di atas.
<refreshVisibility>	tidak
<Region>	ya
<ResourceMap>	N/A	<Model> tidak didukung
<rightFov>	N/A	<PhotoOverlay> tidak didukung
<roll>	N/A	<Camera> dan <Model> tidak didukung
<rotation>	tidak
<rotationXY>	tidak
<Scale>	N/A	<Model> tidak didukung
<scale>	tidak
<Schema>	tidak
<SchemaData>	tidak
<ScreenOverlay>	ya	tidak bisa diputar
<screenXY>	tidak
<shape>	N/A	<PhotoOverlay> tidak didukung
<SimpleData>	N/A	<SchemaData> tidak didukung
<SimpleField>	N/A	<Schema> tidak didukung
<size>	ya
<Snippet>	ya
<south>	ya
<state>	N/A	<ListStyle> tidak didukung
<Style>	ya
<StyleMap>	tidak	efek gerakan mouse (sorot) tidak didukung
<styleUrl>	N/A	<StyleMap> tidak didukung
<targetHref>	sebagian	didukung di <Update>, tidak di <Alias>
<tessellate>	tidak
<text>	ya	penggantian $[geDirections] tidak didukung
<textColor>	tidak
<tileSize>	N/A	<PhotoOverlay> tidak didukung
<tilt>	tidak
<TimeSpan>	tidak
<TimeStamp>	tidak
<topFov>	N/A	<PhotoOverlay> tidak didukung
<Update>	sebagian	hanya perubahan gaya, bukan <Create> atau <Delete>
<Url>	ya	tidak digunakan lagi
<value>	ya
<viewBoundScale>	tidak
<viewFormat>	tidak
<viewRefreshMode>	sebagian	"onStop" didukung
<viewRefreshTime>	ya
<ViewVolume>	N/A	<PhotoOverlay> tidak didukung
<visibility>	sebagian	ya pada <Folder> - placemark turunan mewarisi keterlihatannya
<w>	ya	tidak digunakan lagi
<west>	ya
<when>	N/A	<TimeStamp> tidak didukung
<width>	ya
<x>	ya	tidak digunakan lagi
<y>	ya	tidak digunakan lagi