Maps JavaScript API アプリケーションを V2 から V3 にアップグレードする

Maps JavaScript API v2 は、2021 年 5 月 26 日をもってご利用いただけなくなりました。その結果、お客様のサイトの v2 のマップは機能しなくなり、JavaScript エラーが返されます。サイト上でマップを引き続き使用するには、Maps JavaScript API v3 に移行してください。このガイドでは、このプロセスについて説明します。

概要

アプリケーションごとに移行プロセスは多少異なりますが、すべてのプロジェクトに共通する手順があります。

  1. 新しいキーを取得します。Maps JavaScript API が Google Cloud Console を使用して鍵を管理するようになりました。v2 鍵を使用している場合は、移行を開始する前に新しい API キーを取得してください。
  2. API ブートストラップを更新します。ほとんどのアプリケーションでは、次のコードを使用して Maps JavaScript API v3 を読み込みます。
    <script src="//maps.googleapis.com/maps/api/js?key=YOUR_API_KEY"></script>
    
  3. コードを更新する。必要な変更の量は、アプリケーションによって大きく異なります。一般的な変更は次のとおりです。
    • 常に google.maps 名前空間を参照します。v3 では、すべての Maps JavaScript API コードはグローバル名前空間ではなく、google.maps.* 名前空間に保存されます。ほとんどのオブジェクトは、このプロセスの一環として名前も変更されています。たとえば、GMap2 の代わりに google.maps.Map を読み込みます。
    • 古いメソッドへの参照をすべて削除します。GDownloadURLGLog など、いくつかの汎用ユーティリティ メソッドが削除されました。 この機能をサードパーティのユーティリティ ライブラリに置き換えるか、これらの参照をコードから削除してください。
    • (省略可)コードにライブラリを追加します。多くの機能はユーティリティ ライブラリに外部化されているため、アプリは API の一部を読み込むだけで済みます。
    • (省略可)v3 外部設定を使用するようにプロジェクトを構成します。v3 エクステンションを使用して、Closure Compiler によるコードの検証や、IDE でオートコンプリートをトリガーできます。詳しくは、高度なコンパイルと外部クエリをご覧ください。
  4. テストを繰り返す。この時点でまだやるべきことはいくつかありますが、

Maps JavaScript API の V3 における変更点

移行を計画する前に、Maps JavaScript API v2 と Maps JavaScript API v3 の相違点をよく理解する必要があります。最新バージョンの Maps JavaScript API は、最新の JavaScript プログラミング技術、ライブラリの使用促進、シンプルな API に重点を置いて、ゼロから作成されています。多くの新機能が API に追加され、認識済みの機能の一部が変更または削除されています。このセクションでは、2 つのリリースの主な違いについて説明します。

v3 API の主な変更点は次のとおりです。

  • コア ライブラリを簡素化。多くの補足関数がライブラリに移動されました。これにより、Core API の負荷と解析時間を短縮し、あらゆるデバイスで地図をすばやく読み込むことができます。
  • ポリゴン レンダリングやマーカーの配置など、いくつかの機能のパフォーマンスを改善しました。
  • クライアントサイドの使用制限に対する新しいアプローチにより、モバイル プロキシや企業のファイアウォールで使用される共有アドレスに適切に対応できるようになりました。
  • 複数の最新ブラウザとモバイル ブラウザのサポートを追加しました。Internet Explorer 6 のサポートは終了しました。
  • 多くの汎用ヘルパークラス(GLog または GDownloadUrl)が削除されました。現在、ClosurejQuery など、同様の機能を提供する優れた JavaScript ライブラリが数多く存在します。
  • あらゆるモバイル端末でロードされる HTML5 ストリート ビューが実装されました。
  • カスタム ストリートビュー パノラマ: 撮影した写真を使用して、スキーのゲレンデや販売用の住宅などの有名スポットのパノラマ画像を共有できます。
  • スタイル付き地図のカスタマイズ: 基本地図上の要素の表示を、独自のビジュアル スタイルに合わせて変更できるようにします。
  • ElevationServiceDistance Matrix など、複数の新しいサービスをサポートしています。
  • 改善されたルートサービスでは、代替ルート、ルートの最適化(巡回セールスマンの問題のおおよその解決方法)、自転車ルート(自転車レイヤを含む)、乗換案内、ドラッグ可能なルートが提供されます。
  • 更新後の Geocoding 形式で、Geocoding API v2 の accuracy の値より正確なタイプの情報を提供できるようになりました。
  • 1 つのマップで複数の情報ウィンドウをサポート

アプリケーションのアップグレード

新しいキー

Maps JavaScript API v3 は、v2 の新しい鍵システムを使用します。アプリケーションですでに v3 鍵を使用している場合、変更は必要ありません。確認するには、key パラメータで Maps JavaScript API を読み込む URL を確認します。キー値が 'ABQIAA' で始まる場合は、v2 キーを使用します。v2 鍵がある場合は、移行の一環として v3 鍵にアップグレードする必要があります。これにより、次のことが可能になります。

キーは、Maps JavaScript API v3 を読み込むときに渡されます。API キーの生成について学習する

Google Maps API for Work をご利用の場合は、key パラメータではなく、client パラメータでクライアント ID を使用している可能性があります。クライアント ID は Maps JavaScript API v3 でも引き続きサポートされます。鍵のアップグレード プロセスを行う必要はありません。

API の読み込み

コードに加える必要がある最初の変更には、API の読み込み方法が含まれます。v2 では、http://maps.google.com/maps へのリクエストによって Maps JavaScript API を読み込みます。Maps JavaScript API v3 を読み込む場合、次の変更を行う必要があります。

  1. //maps.googleapis.com/maps/api/js から API を読み込む
  2. file パラメータを削除します。
  3. key パラメータを新しい v3 鍵で更新します。Google Maps API for Work ユーザーは、client パラメータを使用する必要があります。
  4. (Google Maps Platform プレミアム プランのみ)Google Maps Platform プレミアム プランのデベロッパー ガイドで説明されているように、client パラメータが指定されていることを確認します。
  5. v パラメータを削除して、最新のリリース バージョンをリクエストするか、v3 のバージョニング スキームに応じて値を変更します。
  6. (省略可)hl パラメータを language に置き換え、その値を保持します。
  7. (省略可)libraries パラメータを追加して、オプションのライブラリを読み込みます。

最も単純なケースでは、v3 ブートストラップで API キーパラメータのみを指定します。

<script src="//maps.googleapis.com/maps/api/js?key=YOUR_API_KEY"></script>

以下の例では、ドイツ語の Maps JavaScript API v2 の最新バージョンをリクエストしています。

<script src="//maps.google.com/maps?file=api&v=2.x&key=YOUR_API_KEY&hl=de"></script>

次の例は、v3 の場合の同等のリクエストです。

<script src="//maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&language=de"></script>

google.maps 名前空間の導入

Maps JavaScript API v3 の最も大きな変更点は、google.maps 名前空間の導入です。v2 API では、デフォルトですべてのオブジェクトがグローバル名前空間に配置されるため、名前が競合する可能性があります。v3 内では、すべてのオブジェクトは google.maps 名前空間内に配置されます。

アプリケーションを v3 に移行する場合は、新しい名前空間を利用するためにコードを変更する必要があります。「G」で検索し、代わりに「google.maps." Won」を使用するのは簡単ではありません。ただし、一般的には、コードを確認する際に適用することをおすすめします。v2 と v3 での同等のクラスの例を以下に示します。

v2 v3
GMap2 google.maps.Map
GLatLng google.maps.LatLng
GInfoWindow google.maps.InfoWindow
GMapOptions google.map.MapOptions
G_API_VERSION google.maps.version
GPolyStyleOptions google.maps.PolygonOptions
or google.maps.PolylineOptions

廃止されたコードの削除

Maps JavaScript API v3 には、v2 の機能のほとんどの部分が類似しています。ただし、サポートが終了したクラスもあります。移行の一環として、これらのクラスをサードパーティのユーティリティ ライブラリに置き換えるか、これらの参照をコードから削除してください。ClosurejQuery など、同様の機能を提供する優れた JavaScript ライブラリが数多く存在します。

Maps JavaScript API v3 では、次のクラスは並列処理されません。

GBoundsGLanguage
GBrowserIsCompatibleGLayer
GControlGLog
GControlAnchorGMercatorProjection
GControlImplGNavLabelControl
GControlPositionGObliqueMercator
GCopyrightGOverlay
GCopyrightCollectionGPhotoSpec
GDownloadUrlGPolyEditingOptions
GDraggableObjectGScreenOverlay
GDraggableObjectOptionsGStreetviewFeatures
GFactualGeocodeCacheGStreetviewLocation
GGeoAddressAccuracyGStreetviewOverlay
GGeocodeCacheGStreetviewUserPhotosOptions
GGoogleBarGTileLayerOptions
GGoogleBarAdsOptionsGTileLayerOverlayOptions
GGoogleBarLinkTargetGTrafficOverlayOptions
GGoogleBarListingTypesGUnload
GGoogleBarOptionsGXml
GGoogleBarResultListGXmlHttp
GInfoWindowTabGXslt
GKeyboardHandler

コードの比較

v2 API と v3 API で記述された 2 つの単純なアプリケーションを比較してみましょう。

<!DOCTYPE html>
<html>
  <head>
    <script src="//maps.google.com/maps?file=api&v=2&key=YOUR_API_KEY"></script>
    <style>
      html, body, #map { height: 100%; margin: 0; }
    </style>
    <script>
    function initialize() {
      if (GBrowserIsCompatible()) {
        var map = new GMap2(
            document.getElementById('map'));
        map.setCenter(new GLatLng(37.4419, -122.1419), 13);
        map.setUIToDefault();

        map.addOverlay(new GMarker(new GLatLng(37.4419, -122.1419)));

      }
    }
    </script>
  </head>
  <body onload="initialize()" onunload="GUnload()">
    <div id="map"></div>
  </body>
</html>
    
<!DOCTYPE html>
<html>
  <head>
    <script src="//maps.googleapis.com/maps/api/js?key=YOUR_API_KEY"></script>
    <style>
      html, body, #map { height: 100%; margin: 0; }
    </style>
    <script>
    function initialize() {
      var map = new google.maps.Map(
        document.getElementById('map'), {
          center: new google.maps.LatLng(37.4419, -122.1419),
          zoom: 13,
          mapTypeId: google.maps.MapTypeId.ROADMAP
      });

      var marker = new google.maps.Marker({
            position: new google.maps.LatLng(37.4419, -122.1419),
            map: map
      });

    }
    google.maps.event.addDomListener(window, 'load', initialize);
    </script>
  </head>
  <body>
    <div id="map"></div>
  </body>
</html>
    

この表からわかるように、2 つのアプリにはいくつかの違いがあります。主な変更点は、以下のとおりです。

  • API のロード元のアドレスが変更されています。
  • GBrowserIsCompatible() メソッドと GUnload() メソッドは v3 では不要になったため、API から削除されました。
  • API オブジェクトでは、GMap2 オブジェクトは google.maps.Map に置き換えられます。
  • プロパティは、Options クラスを通じて読み込まれるようになりました。上の例では、インラインで MapOptions オブジェクトを使用して、地図の読み込みに必要な 3 つのプロパティ(centerzoommapTypeId)を設定しました。
  • V3 では、デフォルト ユーザー インターフェースがデフォルトでオンになっています。これを無効にするには、MapOptions オブジェクトで disableDefaultUI プロパティを true に設定します。

まとめ

この時点で、Maps JavaScript API の v2 から v3 への移行に伴う主なポイントのいくつかを体験できます。他にも知っておく必要がある情報がありますが、アプリケーションによって異なります。以降のセクションでは、発生する可能性のある特定のケースの移行手順について説明します。アップグレード プロセスに役立つリソースもあります。

この記事について問題やご不明な点がございましたら、このページの上部にある [フィードバックを送信] リンクを使用してください。

詳細な参照情報

このセクションには、Maps JavaScript API の v2 と v3 の主な特長の詳細な比較が表示されます。リファレンスの各セクションは個別に読むように設計されています。この資料の全文はお読みいただくことをおすすめします。代わりに、この資料を使用して、移行の計画を立てる際に役立ちます。

  • イベント: イベントの登録と処理を行います。
  • コントロール - 地図上に表示されるナビゲーション コントロールを操作します。
  • オーバーレイ - 地図上のオブジェクトを追加、編集します。
  • マップタイプ - 基本地図を構成するタイル。
  • レイヤ - KML レイヤやトラフィック レイヤなどの、グループとしてのコンテンツの追加と編集。
  • サービス - Google のジオコーディング、ルート、ストリートビュー サービスを使用します。

イベント

Maps JavaScript API v3 のイベントモデルは、v2 で使用されているものと似ていますが、内部的には多くの変更が行われています。

コントロール

Maps JavaScript API には、ユーザーが地図の操作に使用できる UI コントロールが表示されます。API を使用すると、これらのコントロールの表示方法をカスタマイズできます。

オーバーレイ

オーバーレイは、地図に「追加」したオブジェクトを反映して、ポイント、ライン、エリア、またはオブジェクトの集合を示します。

マップタイプ

v2 と v3 では使用可能な地図の種類が若干異なりますが、基本的な地図の種類はすべて API の両方のバージョンで利用できます。デフォルトでは、v2 は標準の「絵を描く」道路地図タイルを使用します。ただし、v3 では、google.maps.Map オブジェクトの作成時に特定のマップタイプを指定する必要があります。

レイヤ

レイヤは、1 つ以上のオーバーレイで構成される地図上のオブジェクトです。単一のユニットとして操作でき、通常はオブジェクトのコレクションを反映します。

サービス