KmlLayer は、KML 要素と GeoRSS 要素を Google Maps JavaScript API タイル オーバーレイにレンダリングします。
概要
Google Maps JavaScript API は、地理情報を表示するために KML および GeoRSS データ形式をサポートします。これらのデータ形式は、KmlLayer オブジェクトを使用してマップ上に表示されます。このオブジェクトのコンストラクタは公開されてアクセス可能な KML または GeoRSS ファイルの URL を受け取ります。
Maps JavaScript API は、提供された地理 XML データを KML 表現に変換します。これが、Maps JavaScript API タイル オーバーレイによってマップ上に表示されます。この KML は、通常の Maps JavaScript API オーバーレイ要素と外見が（動作もいくぶん）似ています。KML <Placemark> および GeoRSS point 要素は、マーカーとしてレンダリングされます。たとえば、<LineString> 要素はポリラインとしてレンダリングされ、<Polygon> 要素はポリゴンとしてレンダリングされます。同様に、<GroundOverlay> 要素はマップ上で矩形画像としてレンダリングされます。ただし、これらのオブジェクトは Google Maps JavaScript API の Markers、Polylines、Polygons または GroundOverlays ではなく、マップ上の単一のオブジェクトにレンダリングされることに注意してください。
KmlLayer オブジェクトは、その map プロパティが設定されるとマップ上に表示されます。setMap() を呼び出して null を渡すと、オブジェクトをマップから除去できます。KmlLayer オブジェクトは、マップの所定の範囲に対して適切な地物を自動的に取得することで、これらの子要素のレンダリングを管理します。範囲が変更されると、現在のビューポート内の地物が自動的にレンダリングされます。
KmlLayer 内のコンポーネントはオンデマンドでレンダリングされるため、レイヤを使用することで多数のマーカー、ポリライン、およびポリゴンのレンダリングの管理が容易になります。これらの構成要素オブジェクトに直接アクセスすることはできませんが、それぞれのオブジェクトには、これらの個別のオブジェクト上のデータを返すクリック イベントがあります。
KML レイヤのオプション
KmlLayer() コンストラクタは、オプションで多数のKmlLayerOptions を渡します。
mapは、KmlLayerをレンダリングするMapを指定します。setMap()メソッド内でこの値をnullに設定すると、KmlLayerを非表示にできます。preserveViewportは、レイヤの表示時にマップがKmlLayerのコンテンツの領域に合わせて調節されないようにします。デフォルトでは、KmlLayerの表示時に、マップはレイヤのコンテンツ全体が表示されるようにズームと位置決めが行われます。suppressInfoWindowsは、KmlLayer内のクリック可能な地物がInfoWindowオブジェクトの表示をトリガーしないようにします。
さらに、KmlLayer がレンダリングされると、レイヤの名前、説明、スニペットおよび作成者を含む変更不能な metadata プロパティが KmlLayerMetadata オブジェクト リテラル内に含まれます。この情報は、getMetadata() メソッドを使用して確認できます。KmlLayer オブジェクトのレンダリングには外部サーバーへの非同期通信が必要であるため、プロパティが指定されたことを示す metadata_changed イベントのリッスンが必要となります。
次の例では、指定された GeoRSS フィードから KmlLayer を構築しています。
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);
}
次の例では、指定された KML フィードから KmlLayer を構築しています。
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
});
}
KML 地物の詳細
KML には多数の地物が含まれている場合があるため、KmlLayer オブジェクトから直接地物データにアクセスすることはできません。代わりに、地物は表示されるときに、クリック可能な Maps JavaScript API オーバーレイに見えるようにレンダリングされます。デフォルトでは、個々の地物をクリックすると、該当する地物に関する KML <title> および <description> 情報を含む InfoWindow が表示されます。また、KML 地物をクリックすると、KmlMouseEvent が生成されます。これにより、次の情報が渡されます。
positionは、KML 地物のInfoWindowが固定されている緯度/経度座標を示します。この位置は、通常はポオリジンリゴン、ポリラインおよび GroundOverlay のクリック位置ですが、マーカーの場合は実際のオリジンです。pixelOffsetは、InfoWindowの「尾」の部分を固定する上記のpositionからのオフセットを示します。ポリゴン オブジェクトの場合、このオフセットは通常0,0ですが、マーカーの場合はマーカーの高さが含まれます。featureDataには、KmlFeatureDataの JSON 構造が含まれます。
次に、KmlFeatureData オブジェクトの例を示します。
{
author: {
email: "nobody@google.com",
name: "Mr Nobody",
uri: "http://example.com"
},
description: "description",
id: "id",
infoWindowHtml: "html",
name: "name",
snippet: "snippet"
}
次の例では、KML 地物がクリックされたときに地物の <Description> テキストがサイドの <div> 内に表示されます。
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;
}
}
KML レンダリングのサイズと複雑さに関する制限
Google Maps JavaScript API には、読み込む KML ファイルのサイズと複雑さに関する制限があります。以下に、現在の制限の概要を示します。
注: これらの制限は、いつでも変更される可能性があります。
- 取得される最大ファイルサイズ（未加工の KML、未加工の GeoRSS、または圧縮された KMZ）
- 3MB
- 圧縮されていない KML ファイルの最大サイズ
- 10MB
- ネットワーク リンクの最大数
- 10
- ドキュメント全体における地物の最大合計数
- 1,000
- KML レイヤの数
- 1 つの Google マップ上に表示可能な KML レイヤの数には制限があります。この制限を超えると、マップ上には一切レイヤが表示されず、ウェブブラウザの JavaScript コンソールでエラーが報告されます。この制限は、作成された KMLLayer クラスの数と、それらのレイヤの作成に使用されたすべての URL の合計長に基づいています。新しく作成する KMLLayer はそれぞれ、レイヤの制限を一部消費し、KML ファイルの読み込み元 URL の長さに応じて、さらにその制限を消費します。そのため、追加できるレイヤ数はアプリケーションによって異なります。平均で、制限に達することなく 10～20 のレイヤを読み込むことができます。それでも制限に達する場合は、短縮 URL サービス（https://goo.gl など）を使用して KML URL を短縮します。または、各 KML URL を参照する NetworkLink から成る KML ファイルを 1 つ作成します。
サポートされる KML 要素
Google Maps JavaScript API は次の KML 要素をサポートします。KML パーサーは通常、不明な XML タグを暗黙的に無視します。
- 場所マーカー
- アイコン
- フォルダ
- 説明的な HTML: <BalloonStyle> および <text> を使用したエンティティの置換
- KMZ（圧縮された KML、添付画像など）
- ポリラインとポリゴン
- ポリラインとポリゴンのスタイル（色、塗りつぶし、不透明度など）
- データを動的にインポートするためのネットワーク リンク
- 地面オーバーレイと画面オーバーレイ
次の表に、サポートされる KML 要素の詳細をすべて記載しています。
| KML 要素 | API でサポートされているか | コメント |
|---|---|---|
| <address> | no | |
| <AddressDetails> | いいえ | |
| <Alias> | 該当せず | <Model> はサポートされません。 |
| <altitude> | いいえ | |
| <altitudeMode> | いいえ | |
| <atom:author> | はい | |
| <atom:link> | はい | |
| <atom:name> | はい | |
| <BalloonStyle> | 一部 | <text> のみがサポートされます。 |
| <begin> | 該当せず | <TimeSpan> はサポートされません。 |
| <bgColor> | いいえ | |
| <bottomFov> | 該当せず | <PhotoOverlay> はサポートされません。 |
| <Camera> | いいえ | |
| <Change> | 一部 | スタイルの変更のみがサポートされます。 |
| <color> | 一部 | #AABBGGRR と #BBGGRR を含みます。<IconStyle>、<ScreenOverlay>、および <GroundOverlay> ではサポートされません。 |
| <colorMode> | no | |
| <cookie> | no | |
| <coordinates> | はい | |
| <Create> | いいえ | |
| <Data> | はい | |
| <Delete> | いいえ | |
| <description> | はい | HTML コンテンツは許可されていますが、クロスブラウザ攻撃から保護するためにサニタイズされます。$[dataName] 形式でのエンティティティ置換はサポートされていません。 |
| <displayMode> | いいえ | |
| <displayName> | いいえ | |
| <Document> | 一部 | 暗黙的に子がサポートされます。その他の機能の子としては機能しません。 |
| <drawOrder> | no | |
| <east> | はい | |
| <end> | 該当せず | <TimeSpan> はサポートされません。 |
| <expires> | はい | 詳細については、まとめのセクションをご覧ください。 |
| <ExtendedData> | 一部 | 型なしの <Data> のみ。<SimpleData> と <Schema>、$[dataName] 形式でのエンティティの置換はサポートされません。
|
| <extrude> | いいえ | |
| <fill> | はい | |
| <flyToView> | no | |
| <Folder> | はい | |
| <geomColor> | no | サポート終了 |
| <GeometryCollection> | no | サポート終了 |
| <geomScale> | no | サポート終了 |
| <gridOrigin> | 該当せず | <PhotoOverlay> はサポートされません。 |
| <GroundOverlay> | はい | 回転はできません。 |
| <h> | はい | サポート終了 |
| <heading> | はい | |
| hint | はい | target=... がサポートされます。 |
| <hotSpot> | はい | |
| <href> | はい | |
| <httpQuery> | いいえ | |
| <Icon> | はい | 回転はできません。 |
| <IconStyle> | はい | |
| <ImagePyramid> | 該当せず | <PhotoOverlay> はサポートされません。 |
| <innerBoundaryIs> | はい | 暗黙的に <LinearRing> を含みます。 |
| <ItemIcon> | 該当せず | <ListStyle> はサポートされません。 |
| <key> | 該当せず | <StyleMap> はサポートされません。 |
| <kml> | はい | |
| <labelColor> | no | サポート終了 |
| <LabelStyle> | いいえ | |
| <latitude> | はい | |
| <LatLonAltBox> | はい | |
| <LatLonBox> | はい | |
| <leftFov> | 該当せず | <PhotoOverlay> はサポートされません。 |
| <LinearRing> | はい | |
| <LineString> | はい | |
| <LineStyle> | はい | |
| <Link> | はい | |
| <linkDescription> | no | |
| <linkName> | no | |
| <linkSnippet> | no | |
| <listItemType> | 該当せず | <ListStyle> はサポートされません。 |
| <ListStyle> | いいえ | |
| <Location> | 該当せず | <Model> はサポートされません。 |
| <Lod> | はい | |
| <longitude> | はい | |
| <LookAt> | いいえ | |
| <maxAltitude> | はい | |
| <maxFadeExtent> | はい | |
| <maxHeight> | 該当せず | <PhotoOverlay> はサポートされません。 |
| <maxLodPixels> | はい | |
| <maxSessionLength> | いいえ | |
| <maxWidth> | 該当せず | <PhotoOverlay> はサポートされません。 |
| <message> | no | |
| <Metadata> | no | サポート終了 |
| <minAltitude> | はい | |
| <minFadeExtent> | はい | |
| <minLodPixels> | はい | |
| <minRefreshPeriod> | いいえ | <NetworkLink> |
| <Model> | いいえ | |
| <MultiGeometry> | 一部 | レンダリングされますが左側のパネルに個別の地物として表示されます。 |
| <name> | はい | |
| <near> | 該当せず | <PhotoOverlay> はサポートされません。 |
| <NetworkLink> | はい | |
| <NetworkLinkControl> | 一部 | <Update> と <expires> は一部サポートされます。API は HTTP ヘッダーの有効期限の設定を無視して、KML で指定した有効期限の設定を使用します。有効期限が設定されていない、または有効期限内の場合、Google マップはインターネットから取得したデータを不特定の期間にわたってキャッシュします。インターネットからデータを再取得するように強制するには、ドキュメントの名前を変更する、別の URL でデータを取得する、またはドキュメントに適切な有効期限を指定する方法があります。 |
| <north> | はい | |
| <open> | はい | |
| <Orientation> | 該当せず | <Model> はサポートされません。 |
| <outerBoundaryIs> | はい | 暗黙的に <LinearRing> を含みます。 |
| <outline> | はい | |
| <overlayXY> | いいえ | |
| <Pair> | 該当せず | <StyleMap> はサポートされません。 |
| <phoneNumber> | no | |
| <PhotoOverlay> | いいえ | |
| <Placemark> | はい | |
| <Point> | はい | |
| <Polygon> | はい | |
| <PolyStyle> | はい | |
| <range> | はい | |
| <refreshInterval> | 一部 | <Link> のみ。<Icon> は不可。 |
| <refreshMode> | はい | "onExpire" モードでは HTTP ヘッダーはサポートされません。上記の <Update> と <expires> の注記を参照してください。 |
| <refreshVisibility> | いいえ | |
| <Region> | はい | |
| <ResourceMap> | 該当せず | <Model> はサポートされません。 |
| <rightFov> | 該当せず | <PhotoOverlay> はサポートされません。 |
| <roll> | 該当せず | <Camera> と <Model> はサポートされません。 |
| <rotation> | no | |
| <rotationXY> | no | |
| <Scale> | 該当せず | <Model> はサポートされません。 |
| <scale> | no | |
| <Schema> | no | |
| <SchemaData> | no | |
| <ScreenOverlay> | はい | 回転はできません。 |
| <screenXY> | no | |
| <shape> | 該当せず | <PhotoOverlay> はサポートされません。 |
| <SimpleData> | 該当せず | <SchemaData> はサポートされません。 |
| <SimpleField> | 該当せず | <Schema> はサポートされません。 |
| <size> | はい | |
| <Snippet> | はい | |
| <south> | はい | |
| <state> | 該当せず | <ListStyle> はサポートされません。 |
| <Style> | はい | |
| <StyleMap> | no | ロールオーバー（ハイライト）効果はサポートされません。 |
| <styleUrl> | 該当せず | <StyleMap> はサポートされません。 |
| <targetHref> | 一部 | <Update> でサポートされますが、<Alias> ではサポートされません。 |
| <tessellate> | no | |
| <text> | はい | $[geDirections] の置換はサポートされません。 |
| <textColor> | no | |
| <tileSize> | 該当せず | <PhotoOverlay> はサポートされません。 |
| <tilt> | no | |
| <TimeSpan> | no | |
| <TimeStamp> | no | |
| <topFov> | 該当せず | <PhotoOverlay> はサポートされません。 |
| <Update> | 一部 | スタイルの変更のみ。<Create> や <Delete> は不可。 |
| <Url> | はい | サポート終了 |
| <value> | はい | |
| <viewBoundScale> | no | |
| <viewFormat> | no | |
| <viewRefreshMode> | 一部 | "onStop" がサポートされます。 |
| <viewRefreshTime> | はい | |
| <ViewVolume> | 該当せず | <PhotoOverlay> はサポートされません。 |
| <visibility> | 一部 | <Folder> では「はい」。子の場所マーカーが可視性を継承します。 |
| <w> | はい | サポート終了 |
| <west> | はい | |
| <when> | 該当せず | <TimeStamp> はサポートされません。 |
| <width> | はい | |
| <x> | はい | サポート終了 |
| <y> | はい | サポート終了 |
ご不明な点がありましたら、Google の