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 を読み込むようになります。
    • 非推奨のメソッドへの参照をすべて削除します。GDownloadURLGLog など、汎用ユーティリティ メソッドがいくつか削除されました。この機能をサードパーティのユーティリティ ライブラリに置き換えるか、コードからこれらの参照を削除します。
    • (省略可)コードにライブラリを追加します。多くの機能がユーティリティ ライブラリに外部化されているため、各アプリは使用する API の部分のみを読み込む必要があります。
    • (省略可)v3 外部関数を使用するようにプロジェクトを構成します。v3 外部関数は、Closure コンパイラでコードを検証したり、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 など)を削除しました。現在、ClosurejQuery など、同様の機能を提供する優れた JavaScript ライブラリが数多く存在します。
  • あらゆるモバイル端末でロードされる HTML5 ストリート ビューが実装されました。
  • 自分の写真で作成したカスタム ストリートビューのパノラマ。スキー場、売家、その他の興味深い場所のパノラマを共有できます。
  • スタイル付き地図のカスタマイズ: 基本地図上の要素の表示を変更して、独自の視覚スタイルに合わせて表示できます。
  • ElevationServiceDistance 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 Namespace 内に配置されます。

アプリケーションを 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 のほとんどの機能に対応するクラスがありますが、サポートが終了したクラスもあります。移行の一環として、これらのクラスをサードパーティのユーティリティ ライブラリに置き換えるか、コードからこれらの参照を削除する必要があります。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 から削除されました。
  • GMap2 オブジェクトは、API の中心オブジェクトとして google.maps.Map に置き換えられます。
  • プロパティは、Options クラスを通じて読み込まれるようになりました。上記の例では、地図の読み込みに必要な 3 つのプロパティ(centerzoommapTypeId)を、インライン化された MapOptions オブジェクトを介して設定しています。
  • 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 つ以上のオーバーレイで構成される地図上のオブジェクトです。これらは 1 つの単位として操作でき、通常はオブジェクトのコレクションを反映します。

サービス