KmlLayer の移行パス

はじめに

このガイドでは、KmlLayer の最も一般的な用途について説明し、代替実装への対応する移行パスを提供します。この情報は、KmlLayer の廃止予定により、その使用から移行する必要があるデベロッパーを対象としています。KmlLayer をサポートする最後のバージョンは 3.65 で、2027 年 5 月に廃止されます。

移行パスは、KmlLayer の使用方法によって異なります。

境界線/国境/関心領域の情報をスタイル設定する KML ファイル: Google の境界データを使用して、行政区域の境界線用データドリブンスタイル設定（DDS）を使用します。
ベクターデータ（ポイント/ポリライン/境界/ポリゴン）を含む KML ファイル: データセット用の DDS、GeoJSON、または deck.gl や geoxml3 などのサードパーティライブラリを使用します。
インタラクティブな要素を含む KML ファイル: 手動のイベントリスナーとカスタム情報ウィンドウを実装して、フィーチャーの操作を行います。
画像を含む KML ファイル: 画像オーバーレイには GroundOverlays またはサードパーティ製パーサーを使用します。
ネットワークリンクを含む KML ファイル: 各 KML を個別のデータセットとしてアップロードするか、KML を統合します。動的データを表示する場合は、Datasets API を使用してデータセットを更新します。
KML を使用してスクリーンオーバーレイを表示する: カスタムコントロールを使用して、ロゴ、凡例、ナビゲーション補助などの固定 UI 要素を置き換えます。

境界線、国境、対象地域の情報をスタイル設定する KML ファイル

KmlLayer を使用して行政境界（特定の国、州、地域をハイライト表示するなど）を表示またはスタイル設定しているデベロッパーは、境界のデータドリブンスタイル設定（DDS）に移行することをおすすめします。

移行に関する推奨事項: 境界線用データドリブンスタイル設定

境界線用データドリブンスタイル設定を使用すると、Google の行政区域境界線ポリゴンに直接アクセスできます。外部 KML ファイルをホストまたは管理することなく、これらの地域にカスタムスタイル（塗りつぶしとストローク）を適用できます。

利用可能な FeatureType

行政区域は機能別に分類され、レベルごとに整理されています。スタイル設定では、次の対象物の種類がサポートされています。

COUNTRY: 国の政治団体。
ADMINISTRATIVE_AREA_LEVEL_1: 国の 1 段階下の行政エンティティ（米国の州など）。
ADMINISTRATIVE_AREA_LEVEL_2: 国レベルの下の 2 次的な行政区画（米国の郡など）。
LOCALITY: 行政区域である都市または町。
POSTAL_CODE: 郵便に使用される郵便番号。
SCHOOL_DISTRICT: 一貫校、小学校、中等教育機関の学区。

これらの対象物の種類を利用できる地域については、境界線の範囲をご覧ください。

エリアをハイライト表示する方法

特定の地域をスタイル設定するには、プレイス ID でターゲットを設定する必要があります。

設定: JavaScript Vector マップタイプ用に構成されたマップ ID を使用し、Google Cloud コンソールで利用可能な地図のレイヤを有効にする必要があります。
実装: 境界ポリゴンのスタイル設定のサンプルコードを使用します。

パン操作を領域に制限する

ハイライト表示された領域の境界ボックスの外にユーザーが移動できないようにするには、MapOptions 内の restriction オプションを使用します。

restriction オブジェクトは、地図の表示可能領域を制限する latLngBounds を定義します。制限の仕組みについて詳しくは、ドキュメントをご覧ください。

// Restrict panning to a specific bounding box
restriction: {
  latLngBounds: {
    north: 47.8,
    south: 45.8,
    east: 10.5,
    west: 5.9,
  },
  strictBounds: true,
},

移行の実装の概要

境界線用データドリブンスタイル設定と地域制限を使用して、地図を特定のエリアにフォーカスする方法の完全な例を次に示します。

const myTargetRegion = "ChIJYW1Zb-9kjEcRFXvLDxG1Vlw"; // Place ID for Switzerland

function initMap() {
  const map = new google.maps.Map(document.getElementById("map"), {
    center: { lat: 46.8, lng: 8.2 },
    zoom: 9,
    mapId: "YOUR_MAP_ID", // Required for DDS
    // Restrict panning to a specific bounding box
    restriction: {
    // Bounding box for Switzerland
      latLngBounds: {
        north: 47.8,
        south: 45.8,
        east: 10.5,
        west: 5.9,
      },
      strictBounds: true,
    },
  });

  // Access the Country layer and style a specific region by Place ID
  const countryLayer = map.getFeatureLayer("COUNTRY");
  countryLayer.style = (options) => {
    if (options.feature.placeId === myTargetRegion) {
      return {
        fillColor: "#FF0000",
        fillOpacity: 0.5,
        strokeColor: "#FF0000",
        strokeWeight: 2,
      };
    } else {
    // Style everything else whited out, to make the area of interest pop out more.
      return {
        fillColor: '#ffffff',
        fillOpacity: 0.8,
      };
    }
  };
}

ベクターデータ（ポイント/ポリライン/境界/ポリゴン）を含む KML ファイル

移行のおすすめ: データセットのデータドリブンスタイル設定

Google は、スタイル設定とパフォーマンスをより詳細に制御しながら、一般公開されている地理データを表示する次の方法をおすすめします。

データセット用データドリブンスタイル設定を利用すれば、独自の地理空間データ（KML、GeoJSON、CSV）をアップロードし、データ属性に基づいてカスタムスタイルを適用して、ベクターマップ上に表示することができます。

1. セットアップとアップロード

実行時に URL を取得する KmlLayer とは異なり、DDS では、Google Cloud コンソールでデータをデータセットとしてホストする必要があります。

マップ ID を作成する: ベクターマップ タイプ用に構成されたマップ ID を使用します。
データセットをアップロードする: KML ファイルを Google Cloud コンソールにアップロードして、一意のデータセット ID を生成します。詳しくは、Maps Datasets の管理方法に関する完全なドキュメントをご覧ください。
データセットを表示する: データセット ID を作成したら、データセットを地図のスタイルとマップ ID に関連付ける必要があります。次に、データセット ID を使用して、地図上にデータを実際に表示します。詳しくは、データセットを地図に追加する方法についての完全なドキュメントをご覧ください。
KML 形式でデータをインポートする場合は、データセットの KML の要件に注意してください。

2. ビューポートをデータに設定する

KmlLayer は、デフォルトでデータの場所に自動的にパンとズームを行います。データセットの DDS では、この動作は自動ではなく、手動で実装する必要があります。

ハードコードされた制限: データ領域が静的な場合は、MapOptions の restriction オプションを使用して、ビューポートを特定の境界にロックします。
動的ズーム: ビューポートを動的に設定するには、データセットの境界ボックスで map.fitBounds() を使用します。

3. 対象物の属性からのスタイル設定

KML ファイルには、DDS が自動的に適用しないスタイル情報（色など）が含まれていることがよくあります。データセット対象物から属性を読み取り、色と不透明度を適用するクライアントサイドのスタイル関数を作成する必要があります。詳しくは、データのスタイルを設定する方法に関するデベロッパー向けドキュメントをご覧ください。

例: 属性を使用した関数のスタイル設定

次の例は、アップロードされたデータセットから background_color 属性と opacity 属性を直接読み取るスタイル関数を作成する方法を示しています。

/**
 * Migration example: Styling features from dataset attributes.
 */
function styleDDSLayer(map, datasetId) {
  const datasetLayer = map.getDatasetFeatureLayer(datasetId);

  // Set the style function
  datasetLayer.style = (params) => {
    // Access attributes defined in your KML/Dataset
    const featureAttributes = params.feature.datasetAttributes;

    // Read style values from attributes, with fallback defaults
    const fillColor = featureAttributes['background_color'] || '#4285F4';
    const fillOpacity = parseFloat(featureAttributes['opacity']) || 0.5;
    const strokeColor = featureAttributes['border_color'] || '#34A853';

    return {
      fillColor: fillColor,
      fillOpacity: fillOpacity,
      strokeColor: strokeColor,
      strokeWeight: 2,
    };
  };
}

インタラクションとスタイル設定の実装について詳しくは、データセットのデータドリブンスタイル設定の概要と動的データの Datasets API をご覧ください。

移行のおすすめ: GeoJSON を使用したクライアントサイドレンダリング

KmlLayer から GeoJSON を使用したクライアントサイドレンダリングに移行するデベロッパーには、Google Maps Platform は、データ形式を変換し、データレイヤを使用してブラウザで直接フィーチャーをレンダリングしてスタイル設定する移行パスをおすすめします。

データレイヤを使用したクライアントサイドレンダリングは、地理データを表示する非常に柔軟な方法です。Google のサーバーでレンダリングされる KmlLayer とは異なり、データレイヤーでは、標準の JavaScript オブジェクトとして機能を利用できます。ただし、大規模なデータセットの場合は、データセットのデータ駆動型スタイル設定などを使用して、データのサーバーサイド処理とレンダリングを行うことをおすすめします。

1. KML を GeoJSON に変換する

最初の手順は、KML ファイルを GeoJSON に変換することです。これには、いくつかの一般的なオープンソースツールを使用できます。

ogr2ogr: GDAL スイートの一部であるこの強力なコマンドラインユーティリティは、多くのベクター形式間で変換できます。

ogr2ogr -f GeoJSON output.json input.kml

togeojson: KML と GPX を GeoJSON に変換するために特別に設計された、テスト済みの小さなツール。

togeojson input.kml > output.json

2. ビューポートをデータに設定する

KmlLayer はデータの場所に自動的にパンとズームを行いますが、データレイヤは行いません。GeoJSON データに合わせてビューポートを設定するには、境界ボックスを手動で計算して map.fitBounds() を呼び出す必要があります。

3. 対象物の属性からのスタイル設定

データレイヤでは、各 GeoJSON フィーチャーから属性（プロパティ）を直接読み取って外観を決定する style 関数を定義できます。

例: スタイリング関数とビューポートの調整

次の例は、GeoJSON データを読み込み、その境界を計算してビューポートを設定し、属性に基づいて対象物をスタイル設定する方法を示しています。

/**
 * Migration example: Loading GeoJSON, fitting viewport, and styling from attributes.
 */
function initMap() {
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 4,
    center: { lat: -28, lng: 137 },
  });

  // Load the GeoJSON data
  map.data.loadGeoJson('path/to/your/data.json', null, (features) => {
    // Adjust viewport to show all loaded features
    const bounds = new google.maps.LatLngBounds();
    features.forEach((feature) => {
      feature.getGeometry().forEachLatLng((latlng) => {
        bounds.extend(latlng);
      });
    });
    map.fitBounds(bounds);
  });

  // Set the style function to read from GeoJSON properties
  map.data.setStyle((feature) => {
    // Access attributes defined in your GeoJSON properties
    const fillColor = feature.getProperty('background_color') || '#4285F4';
    const opacity = parseFloat(feature.getProperty('opacity')) || 0.5;
    const strokeColor = feature.getProperty('border_color') || '#34A853';

    return {
      fillColor: fillColor,
      fillOpacity: opacity,
      strokeColor: strokeColor,
      strokeWeight: 2,
      visible: true
    };
  });
}

データレイヤの使用について詳しくは、地図に GeoJSON をインポートするのドキュメントをご覧ください。

移行パス: サードパーティライブラリを使用したクライアントサイドレンダリング

KmlLayer の代替手段をお探しのデベロッパー向けに、Google Maps Platform JavaScript API で KML データをレンダリングする、コミュニティで管理されているライブラリがいくつかあります。

1. deck.gl

deck.gl は、高性能の WebGL を利用した可視化フレームワークです。GoogleMapsOverlay と GeoJsonLayer を介して、KML レンダリングのほぼドロップインの代替として使用できます。

キャンバスの要件: deck.gl を効果的に使用するには、WebGL レンダリング機能を使用して、地図をベクターマップタイプ（キャンバス要素にレンダリング）を使用するように変換する必要があります。
KML のサポート: ジオメトリの解析は @loaders.gl/kml によって処理され、KML が GeoJSON に変換されます。複雑なスタイル、アイコン、NetworkLink などの KML 機能によっては、手動での実装が必要になる場合があります。
ドキュメント: deck.gl ドキュメント | loaders.gl KML ローダー。
例:
- Google マップの GitHub リポジトリにある deckgl-kml-updated サンプルは、deck.gl を使用してリアルタイムで更新される KML データをレンダリングする方法を示しています。
- deckgl-kml サンプルは、deck.gl を使用して KML データをレンダリングする方法を示しています。

2. geoxml3

geoxml3 は、Google Maps JavaScript API v3 専用に設計された KML プロセッサです。ブラウザで KML をローカルで解析し、マーカー、ポリライン、ポリゴンなどの標準の Google Maps API オブジェクトとしてデータをレンダリングします。

標準地図のサポート: WebGL ベースのソリューションとは異なり、geoxml3 は特定のレンダリングモードを必要とせずに、標準の Google Maps JS API v3 の地図で動作します。
注意点:
- KMZ のサポートが限定的: このライブラリは、KMZ ファイルをネイティブで完全にサポートしていません。通常、KMZ アーカイブを解凍するには、ZipFile.complete.js などのサードパーティのスクリプトとの統合が必要です。
- サポートされていない要素: 3D ジオメトリ、複雑なラベル、特定の新しい KML 要素などの機能はサポートされていません。
ドキュメント: geoxml3 GitHub リポジトリ。

インタラクティブな要素を含む KML ファイル

移行のおすすめ: データセットのデータドリブンスタイル設定

KmlLayer からデータセットのデータドリブンスタイル設定（DDS）に移行するデベロッパー向けに、このガイドでは、自動 KML インタラクションから、マウスのクリックやホバーなどのカスタムの高性能インタラクションに移行する方法について説明します。

初期設定

インタラクションを実装する前に、KML の移行: ベクターデータ ガイドの設定手順に沿って操作したことを確認してください。

マップ ID: [ベクター地図] タイプのマップ ID を構成します。
アップロード: KML データを Google Cloud コンソールにアップロードして、データセット ID を取得します。
レイヤアクセス: map.getDatasetFeatureLayer(datasetId) を使用してインタラクティブレイヤにアクセスします。

1. インタラクションイベントの処理

KmlLayer では、機能のクリックは API によって自動的に処理され、情報ウィンドウが表示されます。データセットの DDS では、データセットレイヤでマウスイベントのリスナーを手動で登録する必要があります。

click: ユーザーが機能をクリックしたときにトリガーされます。
mousemove: カーソルがフィーチャー上を移動したときにトリガーされます。ホバー効果に便利です。

2. 動的スタイル設定（マウスオーバー効果）

DDS スタイルはレイヤにグローバルに適用されるため、どのフィーチャーが操作されているかを追跡し、スタイルを再適用するために、状態変数を維持する必要があります。

let currentFeatureId = null;

function initInteraction(map, datasetId) {
  const datasetLayer = map.getDatasetFeatureLayer(datasetId);

  // Apply the style function
  datasetLayer.style = (params) => {
    const isHovered = params.feature.datasetAttributes['id'] === currentFeatureId;
    return {
      strokeColor: 'green',
      strokeWeight: isHovered ? 4.0 : 2.0, // Bold border on hover
      fillColor: 'green',
      fillOpacity: isHovered ? 0.5 : 0.3,
    };
  };

  // Add interaction listeners
  datasetLayer.addListener('mousemove', (event) => {
    if (event.features.length > 0) {
      currentFeatureId = event.features[0].datasetAttributes['id'];
      datasetLayer.style = datasetLayer.style; // Re-apply style to reflect changes
    }
  });

  // Clear hover state when the mouse leaves the features
  map.addListener('mousemove', () => {
    if (currentFeatureId !== null) {
      currentFeatureId = null;
      datasetLayer.style = datasetLayer.style;
    }
  });
}

3. `description` 属性から HTML を表示する

KML では、<description> タグにデフォルトの情報ウィンドウの HTML が含まれることがよくあります。このデータがデータセットとしてインポートされると、description は特徴属性になります。レンダリングするには、文字列を標準の google.maps.InfoWindow に直接渡します。

const infoWindow = new google.maps.InfoWindow();

datasetLayer.addListener('click', (event) => {
  if (event.features.length > 0) {
    const feature = event.features[0];
    // Access the HTML description attribute
    const htmlContent = feature.datasetAttributes['description'];

    infoWindow.setContent(htmlContent);
    infoWindow.setPosition(event.latLng);
    infoWindow.open(map);
  }
});

4. `ExtendedData` を使用したカスタム情報ウィンドウ

KML で <ExtendedData> を使用してカスタムの名前と値のペアを保存している場合、これらは datasetAttributes にマッピングされます。これらの属性を反復処理して、カスタム HTML ディスプレイを作成できます。

function createCustomContent(feature) {
  const attributes = feature.datasetAttributes;
  const container = document.createElement("div");
  container.style.padding = "10px";
  container.innerHTML = "<h3>Feature Details</h3><dl></dl>";

  const dl = container.querySelector("dl");

  // Iterate through all data attributes imported from KML ExtendedData
  for (const key in attributes) {
    const dt = document.createElement("dt");
    dt.style.fontWeight = "bold";
    dt.textContent = key;

    const dd = document.createElement("dd");
    dd.textContent = attributes[key];

    dl.appendChild(dt);
    dl.appendChild(dd);
  }
  return container;
}

datasetLayer.addListener('click', (event) => {
  if (event.features.length > 0) {
    const content = createCustomContent(event.features[0]);
    infoWindow.setContent(content);
    infoWindow.setPosition(event.latLng);
    infoWindow.open(map);
  }
});

高度な可視化手法については、データの特徴のスタイル設定方法に関するデベロッパー向けドキュメントをご覧ください。

移行のおすすめ: GeoJSON を使用したクライアントサイドレンダリング

KmlLayer から GeoJSON とデータレイヤを使用したクライアントサイドレンダリングに移行するデベロッパー向けに、このガイドでは、自動 KML インタラクションからカスタムのイベントドリブンインタラクションと動的スタイル設定に移行する方法について説明します。

初期設定

インタラクションを実装する前に、KML データを GeoJSON に変換してデータレイヤに読み込む必要があります。ogr2ogr や togeojson などのツールを使用して map.data.loadGeoJson() で地図を初期化する方法について詳しくは、移行のおすすめ: GeoJSON を使用したクライアントサイドレンダリングのガイドをご覧ください。

1. 自動と手動のやり取り

これらのレイヤの主な違いは、ユーザー入力の処理方法です。

KmlLayer: 対象物のクリックを自動的に処理し、KML およびデータを含む InfoWindow を表示します。
データレイヤ: InfoWindow オブジェクトは自動的に表示されません。ユーザー操作をキャプチャするには、イベントリスナーを手動で追加し、データを表示するコードを記述する必要があります。

2. インタラクションイベントの処理

GeoJSON フィーチャーをインタラクティブにするには、map.data オブジェクトで addListener() メソッドを使用します。一般的なイベントは次のとおりです。

click: 情報ウィンドウまたは選択ロジックをトリガーするために使用されます。
mouseover / mouseout: ホバー効果とハイライト表示に使用されます。

3. InfoWindow に HTML の説明を表示する

KML を GeoJSON に変換すると、<description> タグ（通常は HTML を含む）は description という名前のプロパティにマッピングされます。feature.getProperty('description') を使用してこの文字列を取得し、標準の google.maps.InfoWindow 内でレンダリングできます。

const infoWindow = new google.maps.InfoWindow();

// Handle clicks to show the HTML description
map.data.addListener('click', (event) => {
  // Access the 'description' property from the GeoJSON feature
  const htmlContent = event.feature.getProperty('description');

  if (htmlContent) {
    infoWindow.setContent(htmlContent);
    infoWindow.setPosition(event.latLng);
    infoWindow.open(map);
  }
});

4. カスタム情報ウィンドウと `ExtendedData`

元の KML で <ExtendedData> が使用されている場合、これらの名前と値のペアは GeoJSON プロパティに変換されます。データレイヤにはこれらのデフォルトの UI がないため、カスタム InfoWindow を実装して、それらを繰り返し処理して表示する必要があります。

これらの属性には event.feature.getProperty('attribute_name') を使用してアクセスし、カスタム HTML 文字列または DOM 要素を構築して infoWindow.setContent() メソッドに渡すことができます。

5. 動的スタイル設定（マウスオーバー効果）

データレイヤを使用すると、イベントに応じて対象物のスタイルをプログラムで更新できます。overrideStyle() を使用して、機能の外観を一時的に変更し（ホバー時など）、revertStyle() を使用してグローバルスタイルに戻します。

// Set a base style for all features
map.data.setStyle({
  fillColor: 'blue',
  strokeWeight: 1
});

// Highlight feature on mouseover
map.data.addListener('mouseover', (event) => {
  map.data.revertStyle(); // Clear previous highlights
  map.data.overrideStyle(event.feature, {strokeWeight: 8});
});

// Revert style on mouseout
map.data.addListener('mouseout', (event) => {
  map.data.revertStyle();
});

実装の詳細については、データレイヤ: イベント処理とデータレイヤ: 動的スタイル設定に関するドキュメントをご覧ください。

移行パス: サードパーティライブラリを使用したクライアントサイドレンダリング

KmlLayer からサードパーティソリューションに移行するデベロッパー向けに、このガイドでは deck.gl と geoxml3 を使用してマウスのクリックや動的イベントなどのインタラクティブなデータを処理する方法について説明します。

初期設定

インタラクションを実装する前に、移行パス: サードパーティライブラリを使用したクライアントサイドレンダリング ガイドの設定手順に沿って作業を行ってください。これには以下が該当します。

deck.gl: ベクターマップタイプを使用するようにマップを変換します（キャンバス要件）。
geoxml3: 独自のホストからライブラリスクリプトを提供し、クロスオリジンリソースシェアリング（CORS）を管理します。

1. deck.gl を使用したインタラクティブなデータ

deck.gl は KML を直接入力形式としてサポートし、KML ファイルで提供されたデータに基づいてクリックなどのフィーチャー操作を自動的に処理します。

KMLLoader の処理: @loaders.gl/kml モジュールを使用して、ジオメトリとプロパティを deck.gl がネイティブにインタラクションイベントをトリガーするために使用する形式に解析します。
機能のクリック数: 機能がクリックされると、deck.gl はイベントをキャプチャし、関連するメタデータ（<name> や <description> など）を表示できます。
例: deckgl-kml-updated サンプルでは、地震マーカーにカーソルを合わせると詳細なイベント情報が表示されるリアルタイム KML レンダリングが示されています。

2. geoxml3 を使用したインタラクティブなデータ

geoxml3 はブラウザで KML をローカルに解析し、スタイル情報を抽出して、インタラクティブ性を維持する標準の Google Maps API オブジェクトを生成します。

ネイティブスタイル抽出: ライブラリは KML から <Style> 要素と <StyleMap> 要素を取得し、生成されたマーカー、ポリライン、ポリゴンに適用します。
クリックハンドラ: デフォルトでは、geoxml3 はこれらのオブジェクトのクリックハンドラを提供します。パーサーのインスタンス化時にカスタムコールバック関数（createMarker、createOverlay）を定義して、独自の選択ロジックやサイドバーの更新を実装することもできます。
例: この例では、geoxml3 を使用して KML をレンダリングする方法を示します。円形マーカーのカスタマイズや、マーカーをクリックして地震情報を表示するなどのインタラクションも含まれています。
使用パターン:

var myParser = new geoXML3.parser({
  map: map,
  processStyles: true, // Automatically handle KML styles
  afterParse: function(doc) {
    // Code to run after the KML is fully parsed
  }
});
myParser.parse('interactive_data.kml');

画像を含む KML ファイル

KmlLayer を使用して画像（衛星データ、気象パターン、過去の青写真を含む地図など）を表示するデベロッパー向けに、このガイドでは GroundOverlays またはサードパーティ製パーサーへの移行パスについて説明します。

移行のおすすめ: Maps JavaScript API GroundOverlay

画像移行の推奨パスは、google.maps.GroundOverlay クラスを使用することです。これにより、コード内で特定の地理座標に地図上の画像を直接配置できます。

1. 実装

境界を定義するために KML ファイルを使用する代わりに、画像の URL と地図上の長方形を表す LatLngBounds オブジェクトを指定します。

ドキュメント: グラウンドオーバーレイガイド。
画像の準備: 画像がジオリファレンスされているが、正しい投影法（EPSG:4326）で投影されていない場合は、オープンソースツール gdalwarp を使用して画像をワープし、Maps JavaScript API で使用できるようにします。

gdalwarp -t_srs EPSG:4326 image.jp2 image.jpg

移行パス: サードパーティライブラリの使用

ワークフローでデータを KML 形式で保持する必要がある場合は、geoxml3 や deck.gl などのサードパーティライブラリを使用して、画像オーバーレイをレンダリングできます。

免責条項: これらのサードパーティソリューションは Google のサポート対象外です。ただし、テスト済みであり、ほとんどのユースケースで機能します。

1. geoxml3

geoxml3 は、ブラウザでローカルに単純な GroundOverlay 要素を解析して Google Maps API オブジェクトに変換する場合に適しています。

使用例:

const geoXmlParser = new geoXML3.parser({
    map: map,
    afterParse: function(doc) {
        console.log("Parsing complete. Number of documents: " + doc.length);
        const bounds = doc[0].gbounds;
        if (bounds && !bounds.isEmpty()) {
           map.fitBounds(bounds);
        }
    },
    createOverlay: function(groundOverlayData) {
        // Extract bounds and URL from parsed KML data
        const imageUrl = groundOverlayData.icon.href;
        const imageBounds = {
            north: parseFloat(groundOverlayData.latLonBox.north),
            south: parseFloat(groundOverlayData.latLonBox.south),
            east: parseFloat(groundOverlayData.latLonBox.east),
            west: parseFloat(groundOverlayData.latLonBox.west)
        };

        // Create the Google Maps GroundOverlay
        const nativeOverlay = new google.maps.GroundOverlay(imageUrl, imageBounds);
        nativeOverlay.setMap(map);
    }
});
geoXmlParser.parse('your_file.kml');

2. deck.gl

deck.gl の標準の GeoJsonLayer はベクトルデータを処理しますが、BitmapLayer を使用した手動実装により GroundOverlays もサポートできます。

この方法では、KMLLoader を使用してファイルを解析し、KML データから抽出した画像 URL と座標を使用して BitmapLayer を明示的に定義します。

要件: deck.gl を使用するには、ベクターマップ タイプが必要です。
ドキュメント: deck.gl Bitmap Layer

高度なケース: gdal2tiles を使用したタイルピラミッド

画像タイルピラミッドを含む複雑な KML ファイルの場合、移行はより困難になり、画像データの抽出が必要になります。

ツール: gdal2tiles は、KMZ ピラミッドからデータを抽出し、タイルを表示するための標準の Maps JavaScript API コードを生成できます。最終的な結果を既存の地図に組み込むには、手動での変更が必要になる場合があります。

gdal2tiles -z 10- -n -u https://yourhost.com/tiles/ -w google input.kmz

ネットワークリンクを含む KML ファイル

ネットワークリンクを含む KML ファイルを処理するには、KmlLayer の自動クラウドサイド取得から、より明示的なデータ管理戦略に移行する必要があります。

サポートされているソリューション: データセットのデータドリブンスタイル設定（DDS）

Google Maps Platform データセットは <NetworkLink> 要素をネイティブに解析しないため、データ構造に基づいて移行戦略を選択する必要があります。

戦略 A: 個別のデータセット（ユーザー制御レイヤに最適）以前にネットワークリンクだった各 KML ファイルを、Google Cloud コンソールで個別のデータセットとしてアップロードします。次に、JavaScript を使用して、map.getDatasetFeatureLayer(datasetId) を呼び出し、その可視性やスタイルを調整することで、必要に応じてこれらのレイヤを動的に読み込んで表示できます。
戦略 B: フラット化された KML ファイル（パフォーマンスの高い表示に最適） さまざまなネットワークリンクファイルのすべてのフィーチャーを 1 つの包括的な KML ファイルに結合してから、データセットとしてアップロードします。次に、対象物の属性に基づいて動的スタイル設定を使用し、特定のデータサブセットをフィルタしてその場で表示できます。

動的データの更新: ネットワークリンクの「自動更新」の動作を模倣するには、Datasets API を使用して、ソースデータが変更されるたびにデータセットの新しいバージョンをプログラムでアップロードします。

オープンソースソリューション: deck.gl と geoxml3

deck.gl と geoxml3 のどちらも、KML <NetworkLink> 要素の解析と自動取得を強力にサポートしていません。

deck.gl

deck.gl は KMLLoader（togeojson 上に構築）を利用しますが、これは明示的に NetworkLink をサポートしていません。

このソリューションが適切でない理由: パーサーは、信頼性とシンプルさを確保するために、独自のネットワークリクエストを行わない同期型の「手間のかからない」コンバータとして設計されています。アプリケーションが複数の他の URL を指す KML ファイルに依存している場合、deck.gl はそれらを自動的に解決しません。

geoxml3

geoxml3 は Maps JavaScript API の KML を解析するために開発されましたが、ネットワークリンクのサポートは試験運用であり、メンテナンスされていません。

このソリューションが適切でない理由: この機能は、古く、十分にテストされていない特定の「ネットワークリンク」ブランチにのみ存在します。複雑なリンク構造や CORS などの最新のセキュリティ要件を処理できない可能性があるため、本番環境データの移行にこれを使用することはおすすめしません。

推奨事項の概要

信頼性の高い移行を行うには、ネットワークリンクを含むファイルにサードパーティのパーサーを使用するのではなく、Datasets API を使用してデータ取得ロジックを再構築する必要があります。これにより、メンテナンスされていないクライアントサイドのパーサーに依存するのではなく、Google Maps Platform インフラストラクチャ内でデータが安全に管理されます。

KML を使用してスクリーンオーバーレイを表示する

KmlLayer からデータドリブンスタイル設定（DDS）などの最新の代替手段に移行するデベロッパーは、データセットで画面オーバーレイがサポートされていないことに注意する必要があります。地図の上に固定画像、ロゴ、凡例を表示するのと同じ効果を実現するには、Maps JavaScript API を使用してカスタムコントロールを作成する必要があります。

1. KML ファイルで確認すべきこと

同等のカスタムコントロールを構築するには、KML ファイルの <ScreenOverlay> 要素で次のキー属性を確認します。

<Icon><href>: 表示する画像の URL。
<screenXY>: 画面上のオーバーレイの位置を定義します。
- x=0, y=1（分数）は Top Left に対応します。
- x=1, y=1 は右上に対応します。
- x=0, y=0 は左下に対応します。
- x=1, y=0 は右下に対応します。
<size>: オーバーレイの幅と高さを定義します。
<rotation>: 画像を回転させるかどうかを示します。

2. 実装: カスタムコントロールの作成

カスタムコントロールは、基本的に、地図の定義済み位置のいずれかに「プッシュ」する標準の HTML 要素（<div> や <img> など）です。

KML の位置を `ControlPosition` にマッピングする

Maps JavaScript API では、ControlPosition 列挙型を使用してコントロールを固定します。下の表を使用して、KML の <screenXY> を適切な JS API 定数にマッピングします。

KML 位置（`screenXY`）	JS API `ControlPosition`
左上（`x:0, y:1`）	`TOP_LEFT`（以前の課題）または `BLOCK_START_INLINE_START`（論理）
右上（`x:1, y:1`）	`TOP_RIGHT` または `BLOCK_START_INLINE_END`
左下（`x:0, y:0`）	`BOTTOM_LEFT` または `BLOCK_END_INLINE_START`
右下（`x:1, y:0`）	`BOTTOM_RIGHT` または `BLOCK_END_INLINE_END`

3. 移行の例: 固定ロゴのオーバーレイ

次の例は、地図の右上に配置された KML ScreenOverlay ロゴを模倣しています。

CSS スタイル設定

CSS を使用して「オーバーレイ」のサイズと外観を定義します。

#logo-control {
  padding: 10px;
  background-color: rgba(255, 255, 255, 0.8);
  margin: 10px;
  border-radius: 2px;
  box-shadow: 0 1px 4px rgba(0,0,0,0.3);
}

#logo-control img {
  width: 150px; /* Equivalent to KML <size> */
  display: block;
}

JavaScript の実装

要素を map.controls 配列に追加します。

function initMap() {
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 12,
    center: { lat: 41.85, lng: -87.65 },
  });

  // 1. Create the container for the overlay
  const logoControlDiv = document.createElement("div");
  logoControlDiv.id = "logo-control";

  // 2. Create the image (KML <Icon>)
  const logoImage = document.createElement("img");
  logoImage.src = "https://example.com/logo.png";
  logoImage.alt = "Company Logo";

  logoControlDiv.appendChild(logoImage);

  // 3. Position the control (KML <screenXY>)
  // In this case, we use TOP_RIGHT
  map.controls[google.maps.ControlPosition.TOP_RIGHT].push(logoControlDiv);
}

KmlLayer の移行パス コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

はじめに

境界線、国境、対象地域の情報をスタイル設定する KML ファイル

移行に関する推奨事項: 境界線用データドリブン スタイル設定

利用可能な FeatureType

エリアをハイライト表示する方法

パン操作を領域に制限する

移行の実装の概要

ベクターデータ（ポイント/ポリライン/境界/ポリゴン）を含む KML ファイル

移行のおすすめ: データセットのデータドリブン スタイル設定

1. セットアップとアップロード

2. ビューポートをデータに設定する

3. 対象物の属性からのスタイル設定

例: 属性を使用した関数のスタイル設定

移行のおすすめ: GeoJSON を使用したクライアントサイド レンダリング

1. KML を GeoJSON に変換する

2. ビューポートをデータに設定する

3. 対象物の属性からのスタイル設定

例: スタイリング関数とビューポートの調整

移行パス: サードパーティ ライブラリを使用したクライアントサイド レンダリング

1. deck.gl

2. geoxml3

インタラクティブな要素を含む KML ファイル

移行のおすすめ: データセットのデータドリブン スタイル設定

初期設定

1. インタラクション イベントの処理

2. 動的スタイル設定（マウスオーバー効果）

3. description 属性から HTML を表示する

4. ExtendedData を使用したカスタム情報ウィンドウ

移行のおすすめ: GeoJSON を使用したクライアントサイド レンダリング

初期設定

1. 自動と手動のやり取り

2. インタラクション イベントの処理

3. InfoWindow に HTML の説明を表示する

4. カスタム情報ウィンドウと ExtendedData

5. 動的スタイル設定（マウスオーバー効果）

移行パス: サードパーティ ライブラリを使用したクライアントサイド レンダリング

初期設定

1. deck.gl を使用したインタラクティブなデータ

2. geoxml3 を使用したインタラクティブなデータ

画像を含む KML ファイル

移行のおすすめ: Maps JavaScript API GroundOverlay

1. 実装

移行パス: サードパーティ ライブラリの使用

1. geoxml3

2. deck.gl

高度なケース: gdal2tiles を使用したタイル ピラミッド

ネットワーク リンクを含む KML ファイル

サポートされているソリューション: データセットのデータドリブン スタイル設定（DDS）

オープンソース ソリューション: deck.gl と geoxml3

deck.gl

geoxml3

推奨事項の概要

KML を使用してスクリーン オーバーレイを表示する

1. KML ファイルで確認すべきこと

2. 実装: カスタム コントロールの作成

KML の位置を ControlPosition にマッピングする

3. 移行の例: 固定ロゴのオーバーレイ

CSS スタイル設定

JavaScript の実装

より詳しく

KmlLayer の移行パス

移行に関する推奨事項: 境界線用データドリブンスタイル設定

移行のおすすめ: データセットのデータドリブンスタイル設定

移行のおすすめ: GeoJSON を使用したクライアントサイドレンダリング

移行パス: サードパーティライブラリを使用したクライアントサイドレンダリング

移行のおすすめ: データセットのデータドリブンスタイル設定

1. インタラクションイベントの処理

3. `description` 属性から HTML を表示する

4. `ExtendedData` を使用したカスタム情報ウィンドウ

移行のおすすめ: GeoJSON を使用したクライアントサイドレンダリング

2. インタラクションイベントの処理

4. カスタム情報ウィンドウと `ExtendedData`

移行パス: サードパーティライブラリを使用したクライアントサイドレンダリング

移行パス: サードパーティライブラリの使用

高度なケース: gdal2tiles を使用したタイルピラミッド

ネットワークリンクを含む KML ファイル

サポートされているソリューション: データセットのデータドリブンスタイル設定（DDS）

オープンソースソリューション: deck.gl と geoxml3

KML を使用してスクリーンオーバーレイを表示する

2. 実装: カスタムコントロールの作成

KML の位置を `ControlPosition` にマッピングする