Maps JavaScript API を読み込む

このガイドでは、Maps JavaScript API を読み込む方法について説明します。以下の 3 つの方法で読み込むことができます。

Dynamic Library Import を使用する

Dynamic library import には、実行時にライブラリを読み込む機能があります。これにより、読み込みの際にすべてのライブラリをリクエストするのではなく、必要な時点で必要なライブラリだけをリクエストできるようになります。ページで Maps JavaScript API が複数回読み込まれることも防止できます。

アプリケーション コードにインライン ブートストラップ ローダを追加して、Maps JavaScript API を読み込みます。以下のスニペットをご覧ください。

<script>
  (g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})({
    key: "YOUR_API_KEY",
    v: "weekly",
    // Use the 'v' parameter to indicate the version to use (weekly, beta, alpha, etc.).
    // Add other bootstrap parameters as needed, using camel case.
  });
</script>

別の方法として、ブートストラップ ローダのコードを直接 JavaScript コードに追加することもできます。

実行時にライブラリを読み込むには、await 演算子を使って async 関数内から importLibrary() を呼び出します。以下のサンプルコードのように、必要なクラスの変数を宣言することで修飾パス（google.maps.Map など）の使用を省略できます。

TypeScript

let map: google.maps.Map;
async function initMap(): Promise<void> {
  const { Map } = await google.maps.importLibrary("maps") as google.maps.MapsLibrary;
  map = new Map(document.getElementById("map") as HTMLElement, {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8,
  });
}

initMap();
index.ts

JavaScript

let map;

async function initMap() {
  const { Map } = await google.maps.importLibrary("maps");

  map = new Map(document.getElementById("map"), {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8,
  });
}

initMap();
index.js

関数を使うと、必要なクラスの変数を宣言せずにライブラリを読み込むこともできます。これは、gmp-map 要素を使用してマップを追加する場合に特に便利です。

async function initMap() {
  google.maps.importLibrary("maps");
  google.maps.importLibrary("marker");
}

initMap();

また、次に示すように、HTML でライブラリを直接読み込むこともできます。

<script>
google.maps.importLibrary("maps");
google.maps.importLibrary("marker");
</script>

詳しくは、Dynamic Library Loading API への移行をご覧ください。

必須パラメータ

  • key: 有効な API キー。有効な API キーが指定されない限り、Maps JavaScript API は読み込まれません。

省略可能なパラメータ

  • v: 読み込む Maps JavaScript API のバージョン。

  • libraries: 追加で読み込む Maps JavaScript API ライブラリのリスト（カンマ区切り）。特定のライブラリ群を固定的に指定することは、通常は推奨されませんが、ウェブサイトのキャッシュ動作を微調整したい場合には指定可能です。

  • language: 使用する言語。コントロール名、著作権に関する通知、運転ルート、コントロール ラベル、サービス リクエストへのレスポンスに適用されます。サポートされている言語の一覧をご覧ください。

  • region: 使用するリージョン コード。指定した国または地域に応じて地図の動作が変わります。

  • authReferrerPolicy: Maps JS をご利用の場合、Cloud コンソールで HTTP リファラー制限を設定し、特定の API キーの使用を許可する URL を制限できます。デフォルトでは、特定のパスのみに API キーの使用を許可するように、これらの制限が構成されています。同じドメインまたはオリジンのすべての URL で該当 API キーを使用しても問題ない場合は、authReferrerPolicy: "origin" を設定することで、Maps JavaScript API からのリクエストを承認する際に送信されるデータの量を制限できます。このパラメータが指定されていて、Cloud コンソールで HTTP リファラー制限が有効になっているときは、現在のウェブサイトのドメインに一致する HTTP リファラー制限（パス指定なし）が存在する場合に限り、Maps JavaScript API を読み込むことができます。

  • mapIds: マップ ID の配列。指定されたマップ ID の設定が事前に読み込まれます。

  • channel: 使用状況をチャネルごとにトラッキングをご覧ください。

  • solutionChannel: Google Maps Platform には、すぐに実行できる、さまざまな種類のサンプルコードが用意されています。より複雑なコードサンプルの導入を追跡し、ソリューションの質を向上させるために、Google はサンプルコードの API 呼び出しに solutionChannel クエリ パラメータを含めています。

ダイレクト スクリプト読み込みタグを使用する

このセクションでは、ダイレクト スクリプト読み込みタグを使用する方法を説明します。ダイレクト スクリプトはマップが読み込まれるときにライブラリを読み込むため、実行時にライブラリを明示的にリクエストする必要がなくなり、gmp-map 要素を使用して作成されたマップを簡素化できます。ダイレクト スクリプト読み込みタグは、スクリプトが読み込まれるときにリクエストされたすべてのライブラリを一度に読み込むため、一部のアプリケーションではパフォーマンスが影響を受ける可能性があります。ダイレクト スクリプト読み込みタグは、ページの読み込みごとに 1 回だけ含めてください。

スクリプトタグを追加する

HTML ファイルに Maps JavaScript API をインラインで読み込むには、次のように script タグを追加します。

<script async
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&loading=async&callback=initMap">
</script>

ダイレクト スクリプト読み込み URL パラメータ

このセクションでは、Maps JavaScript API を読み込む際にスクリプト読み込み URL のクエリ文字列で指定できるすべてのパラメータについて説明します。パラメータには、必須パラメータと省略可能なパラメータがあります。URL の標準規則と同様に、すべてのパラメータはアンパサンド（&）文字を使用して区切ります。

次のサンプル URL には、使用できるすべてのパラメータのプレースホルダが含まれています。

https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY
&loading=async
&callback=FUNCTION_NAME
&v=VERSION
&libraries="LIBRARIES"
&language="LANGUAGE"
&region="REGION"
&auth_referrer_policy="AUTH_REFERRER_POLICY"
&map_ids="MAP_IDS"
&channel="CHANNEL"
&solution_channel="SOLUTION_IDENTIFIER"

次のサンプル script タグの URL は、Maps JavaScript API を読み込みます。

<script async
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&loading=async&callback=initMap">
</script>

必須パラメータ（ダイレクト）

Maps JavaScript API を読み込む際、以下のパラメータが必要です。

  • key: 有効な API キー。有効な API キーが指定されない限り、Maps JavaScript API は読み込まれません。

省略可能なパラメータ（ダイレクト）

これらのパラメータを使用すると、Maps JavaScript API の特定のバージョンのリクエスト、追加ライブラリの読み込み、地図のローカライズ、HTTP リファラー チェック ポリシーの指定を行えます。

  • loading: Maps JavaScript API が使用できるコード読み込み戦略。async に設定すると、Maps JavaScript API を同期的に読み込まないことと、スクリプトの load イベントによって JavaScript コードをトリガーしないことが明示されます。パフォーマンスを高めるため、可能であれば async に設定することを強くおすすめします。（Maps JavaScript API を利用できる場合は、代わりに callback パラメータを使用してアクションを実行します）バージョン 3.55 から利用できます。

  • callback: Maps JavaScript API が完全に読み込まれた後に呼び出されるグローバル関数の名前。

  • v: 使用する Maps JavaScript API のバージョン。

  • libraries: 追加で読み込む Maps JavaScript API ライブラリのリスト（カンマ区切り）。

  • language: 使用する言語。このパラメータは、コントロールの名前、著作権に関する通知、運転ルート、コントロール ラベル、サービス リクエストに対するレスポンスに影響します。サポートされている言語の一覧をご覧ください。

  • region: 使用するリージョン コード。指定した国または地域に応じて地図の動作が変わります。

  • auth_referrer_policy: Cloud コンソールで HTTP リファラー制限を設定し、特定の API キーの使用を許可する URL を制限できます。デフォルトでは、特定のパスのみに API キーの使用を許可するように、これらの制限が構成されています。同じドメインの URL または元の URL で API キーを使用できる場合は、auth_referrer_policy=origin を設定して、Maps JavaScript API からのリクエストを承認する際に送信されるデータの量を制限できます。これはバージョン 3.46 以降で可能です。このパラメータが指定されていて、Cloud コンソールで HTTP リファラー制限が有効になっているときは、現在のウェブサイトのドメインに一致する HTTP リファラー制限（パス指定なし）が存在する場合に限り、Maps JavaScript API を読み込むことができます。

  • mapIds: カンマ区切りのマップ ID のリスト。指定されたマップ ID の設定が事前に読み込まれます。

  • channel: 使用状況をチャネルごとにトラッキングをご覧ください。

  • solution_channel: Google Maps Platform には、すぐに実行できる、さまざまな種類のサンプルコードが用意されています。より複雑なコードサンプルの導入を追跡し、ソリューションの質を向上させるために、Google はサンプルコードの API 呼び出しに solution_channel クエリ パラメータを含めています。

NPM js-api-loader パッケージを使用する

@googlemaps/js-api-loader パッケージを使用すると、NPM パッケージ管理システムを介して Maps JavaScript API を読み込むことができます。次のコマンドを使用してパッケージをインストールします。

npm install @googlemaps/js-api-loader

このパッケージは、次のコマンドでアプリケーションにインポートできます。

import { Loader } from "@googlemaps/js-api-loader"

このローダは、Promise とコールバック インターフェースを公開します。以下は、デフォルトの Promise メソッド load() の使用方法を示しています。

TypeScript

const loader = new Loader({
  apiKey: "YOUR_API_KEY",
  version: "weekly",
  ...additionalOptions,
});

loader.load().then(async () => {
  const { Map } = await google.maps.importLibrary("maps") as google.maps.MapsLibrary;
  map = new Map(document.getElementById("map") as HTMLElement, {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8,
  });
});
index.ts

JavaScript

const loader = new Loader({
  apiKey: "YOUR_API_KEY",
  version: "weekly",
  ...additionalOptions,
});

loader.load().then(async () => {
  const { Map } = await google.maps.importLibrary("maps");

  map = new Map(document.getElementById("map"), {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8,
  });
});

index.js

js-api-loader を使用するサンプルをご覧ください。

以下のサンプルでは、loader.importLibrary() を使用してライブラリを読み込んでいます。

const loader = new Loader({
  apiKey: "YOUR_API_KEY",
  version: "weekly",
  ...additionalOptions,
});

loader
  .importLibrary('maps')
  .then(({Map}) => {
    new Map(document.getElementById("map"), mapOptions);
  })
  .catch((e) => {
    // do something
});

Dynamic Library Import API に移行する

このセクションでは、Dynamic Library Import API を使用するよう統合を移行する手順について説明します。

移行の手順

まず、ダイレクト スクリプト読み込みタグをインライン ブートストラップ ローダのタグに置き換えます。

変更前

<script async
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&loading=async&libraries=maps&callback=initMap">
</script>

変更後

<script>
  (g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})({
    key: "YOUR_API_KEY",
    v: "weekly",
    // Use the 'v' parameter to indicate the version to use (weekly, beta, alpha, etc.).
    // Add other bootstrap parameters as needed, using camel case.
  });
</script>

次に、アプリケーション コードを更新します。

  • initMap() 関数を非同期に変更します。
  • importLibrary() を呼び出して必要なライブラリを読み込み、ライブラリにアクセスします。

変更前

let map;

function initMap() {
  map = new google.maps.Map(document.getElementById("map"), {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8,
  });
}

window.initMap = initMap;

変更後

let map;
// initMap is now async
async function initMap() {
    // Request libraries when needed, not in the script tag.
    const { Map } = await google.maps.importLibrary("maps");
    // Short namespaces can be used.
    map = new Map(document.getElementById("map"), {
        center: { lat: -34.397, lng: 150.644 },
        zoom: 8,
    });
}

initMap();