Maps JavaScript API を読み込む

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

Dynamic Library Import を使用する

アプリケーション コードにインライン ブートストラップ ローダを追加して、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() を呼び出します。以下のコードサンプルをご覧ください。

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

必須パラメータ

  • key: 有効な API キー。有効な API キーを指定しなければ、Maps JavaScript API は読み込まれません。

省略可能なパラメータ

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

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

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

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

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

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

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 を使用するサンプルをご覧ください。

以前のスクリプト読み込みタグを使用する

以前のスクリプト読み込みタグも引き続きサポートされています。このセクションでは、以前のスクリプト読み込みタグを使用して Maps JavaScript API を読み込む方法について説明します。なお、Google では Dynamic Library Loading API に移行することを推奨しています。

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

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

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

以前のスクリプト読み込み URL パラメータ

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

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

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

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

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

必須パラメータ（以前）

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

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

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

省略可能なパラメータ（以前）

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

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

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

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

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

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

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

Dynamic Library Import API に移行する

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

移行の手順

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

変更前

<script async
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&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();