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

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

概要

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

  1. 新しい鍵を取得する。Maps JavaScript API では、Google Cloud コンソールを使用してキーを管理するようになりました。まだ 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 を読み込みます。
    • 廃止されたメソッドへの参照をすべて削除します。GDownloadURL や GLog など、多くの汎用ユーティリティ メソッドが削除されました。この機能をサードパーティのユーティリティ ライブラリに置き換えるか、コードからこれらの参照を削除してください。
    • （省略可）コードにライブラリを追加します。多くの機能はユーティリティ ライブラリに外部化されているため、各アプリは API のうち使用する部分を読み込むだけで済みます。
    • （省略可）v3 外部を使用するようにプロジェクトを構成します。v3 エクスターンを使用して、Closure Compiler でコードを検証したり、IDE でオートコンプリートをトリガーしたりできます。詳細については、 高度なコンパイルとエクスターンをご覧ください。
  4. テストを繰り返す。この時点でまだ行うべき作業はありますが、新しい v3 マップ アプリケーションの作成に向けて順調に進んでいることでしょう。

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）を削除しました。現在、Closure や jQuery など、同様の機能を提供する優れた JavaScript ライブラリが多数存在します。
  • あらゆるモバイル端末でロードされる HTML5 ストリート ビューが実装されました。
  • 自分で撮影した写真でカスタム ストリートビュー パノラマを作成して、スキー場や売り場などの興味深い場所のパノラマ画像を共有できます。
  • スタイル付き地図のカスタマイズ: 独自の表示スタイルに合わせて、基本地図の要素の表示を変更できます。
  • ElevationService や Distance Matrix などの新しいサービスをサポートします。
  • 改善されたルートサービスでは、代替ルート、ルートの最適化（ 移動販売員の問題のおおよその解決策）、自転車ルート（ 自転車レイヤを使用）、乗換案内、 ドラッグ可能なルートが提供されます。
  • Geocoding API v2 の accuracy 値よりも正確なタイプ情報を提供するように更新されたジオコーディング形式。
  • 1 つのマップ上での複数の情報ウィンドウのサポート

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

新しいキー

Maps JavaScript API v3 では、v2 から新しいキーシステムが使用されています。アプリケーションですでに v3 鍵を使用している場合、変更は必要ありません。これを確認するには、Maps JavaScript API の読み込み元の URL の key パラメータを確認します。鍵の値が「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. 新しい v3 鍵で key パラメータを更新します。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.」に置き換えても完全には機能しませんが、コードを確認する際は経験則として適用することをおすすめします。以下に、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 のほとんどの機能に対応していますが、一部のクラスのサポートは終了しています。移行の一環として、これらのクラスをサードパーティのユーティリティ ライブラリに置き換えるか、これらの参照をコードから削除する必要があります。Closure や jQuery など、同様の機能を提供する優れた 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 と 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 から削除されました。
  • GMap2 オブジェクトは、API の中心オブジェクトとして google.maps.Map に置き換えられます。
  • プロパティは、Options クラスを通じて読み込まれるようになりました。上記の例では、インラインの MapOptions オブジェクトを介して、地図の読み込みに必要な 3 つのプロパティ（center、zoom、mapTypeId）を設定しています。
  • 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 つ以上のオーバーレイで構成される地図上のオブジェクトです。これらは単一のユニットとして操作でき、通常はオブジェクトの集合を反映します。

サービス