概要

プラットフォームを選択: Android iOS JavaScript

Maps JavaScript API を使用すると、独自のコンテンツと画像を使って地図をカスタマイズして、ウェブページおよびモバイルデバイスに表示できます。Maps JavaScript API で提供されている 4 つの基本地図タイプ（道路地図、衛星、ハイブリッド、地形）に、レイヤとスタイル、コントロールとイベント、さまざまなサービスとライブラリを使用して変更を加えることができます。

対象読者

このドキュメントは、JavaScript のプログラミングとオブジェクト指向プログラミングの概念を理解しているデベロッパーを対象にしています。また、ユーザーの視点でマップを使い慣れていることも必要です。ウェブ上に多数ある JavaScript チュートリアルも参考にしてください。

このドキュメントは、Maps JavaScript API を使ったアプリケーションの検討と開発を速やかに始められるようにするための概要資料です。Maps JavaScript API リファレンスも併せてご覧ください。

Hello World

Maps JavaScript API について理解する最も簡単な方法は、シンプルなサンプルを見ることです。次のサンプルでは、オーストラリアのニューサウスウェールズ州シドニーを中心とする地図が表示されます。

TypeScript

let map: google.maps.Map;
async function initMap(): Promise<void> {
  //@ts-ignore
  const { Map } = await google.maps.importLibrary("maps");
  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() {
  //@ts-ignore
  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

CSS

/*
 * Always set the map height explicitly to define the size of the div element
 * that contains the map.
 */
#map {
  height: 100%;
}

/*
 * Optional: Makes the sample page fill the window.
 */
html,
body {
  height: 100%;
  margin: 0;
  padding: 0;
}
style.css

HTML

<html>
  <head>
    <title>Simple Map</title>
    <script src="https://polyfill.io/v3/polyfill.min.js?features=default"></script>

    <link rel="stylesheet" type="text/css" href="./style.css" />
    <script type="module" src="./index.js"></script>
  </head>
  <body>
    <div id="map"></div>

    <!-- prettier-ignore -->
    <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: "AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg", v: "weekly"});</script>
  </body>
</html>index.html

サンプルを表示

サンプルを試す

Stackblitz.com CodeSandbox.io JSFiddle.net GitPod.io Google Cloud Shell

このシンプルなサンプルでも、注目するべき点がいくつかあります。

<!DOCTYPE html> 宣言を使用して、アプリケーションを HTML5 として宣言しています。
地図を保持する「map」という名前の div 要素を作成しています。
div 内に地図を作成する JavaScript 関数を定義しています。
ブートストラップローダを使用して Maps JavaScript API を読み込みんでいます。

上記のステップについて以下で説明します。

Maps JavaScript API を読み込む

ブートストラップローダーは、Maps JavaScript API を読み込む際に推奨される方法です。代わりに JS API ローダを使用することもできます。両方の方法を検討し、プロジェクトのコードの構造に最も適した方法を選択することをおすすめします。

詳しくは、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_HERE",
    // Add other bootstrap parameters as needed, using camel case.
    // Use the 'v' parameter to indicate the version to load (alpha, beta, weekly, etc.)
  });
</script>

ランタイムにライブラリを読み込むには、非同期関数内で await 演算子を使って importLibrary() を呼び出します。コードは次のようになります。

TypeScript

let map: google.maps.Map;
async function initMap(): Promise<void> {
  //@ts-ignore
  const { Map } = await google.maps.importLibrary("maps");
  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() {
  //@ts-ignore
  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

NPM js-api-loader パッケージ

NPM を使って Maps JavaScript API を読み込むには、@googlemaps/js-api-loader を使用します。このパッケージを実装するには、NPM を介して次のコマンドを使用します。

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

アプリケーションを HTML5 として宣言する

ウェブアプリケーション内で、真の DOCTYPE を宣言することをおすすめします。このサンプルでは、下に示すようにシンプルな HTML5 DOCTYPE を使用して、アプリケーションを HTML5 として宣言しています。

<!DOCTYPE html>

最新のブラウザの大半は、この DOCTYPE で宣言されたコンテンツを「標準モード」でレンダリングします。これは、アプリケーションがより多くのブラウザに対応していることを意味します。DOCTYPE は、スムーズなデグレードも可能にしています。つまり、これを認識しないブラウザはこれを無視し、「後方互換モード」を使用してそのコンテンツを表示します。

後方互換モードで動作する一部の CSS は、標準モードでは有効ではありません。特に、パーセントベースのサイズは親ブロック要素から継承する必要があり、いずれかの祖先でサイズの指定に失敗すると、0×0 ピクセルのサイズとみなされます。この理由から、次の <style> 宣言を含めています。

<style>
  #map {
    height: 100%;
  }
  html, body {
    height: 100%;
    margin: 0;
    padding: 0;
  }
</style>

この CSS 宣言では、地図コンテナ <div>（ID は map）が HTML 本文の高さの 100% を占めることが宣言されます。これらのパーセンテージを、<body> および <html> に対しても同様に明確に宣言する必要があります。

Maps JavaScript API を読み込む

Maps JavaScript API は、script タグを使用して読み込まれます。このタグは HTML ファイルにインラインとして追加するか、別の JavaScript ファイルを使用して動的に追加できます。両方の方法を検討し、プロジェクトのコードの構造に最も適した方法を選択することをおすすめします。

インライン読み込み

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

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

動的読み込み

別の JavaScript ファイルを使用して Maps JavaScript API をインラインで動的に読み込むには、次のサンプルをご覧ください。この方法では、API を使用するためのすべてのコードを別の .js ファイルから処理でき、スクリプトタグをインラインで追加するのと同等の結果を得ることができます。

// Create the script tag, set the appropriate attributes
var script = document.createElement('script');
script.src = 'https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap';
script.async = true;

// Attach your callback function to the `window` object
window.initMap = function() {
  // JS API is loaded and available
};

// Append the 'script' element to 'head'
document.head.appendChild(script);

動的読み込み

@googlemaps/js-api-loader パッケージを使用すると、よりシームレスな動的読み込みが可能になります。NPM を使用して、次のコマンドでインストールできます。

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

スクリプトタグ属性

上記のサンプルでは、script タグに複数の属性が設定されています（推奨）。以下で、各属性について説明します。

src: Maps JavaScript API の読み込み元となる URL。Maps JavaScript API を使用するために必要なすべての記号と定義が含まれます。このサンプルの URL には、API キーを指定する key と、Maps JavaScript API の読み込みが完了すると呼び出されるグローバル関数の名前を指定する callback の 2 つのパラメータがあります。詳しくは、URL パラメータについての記事をご覧ください。
async: スクリプトを非同期でダウンロードして実行するようブラウザに指示します。このスクリプトの実行時に、callback パラメータで指定された関数が呼び出されます。

ライブラリ

URL を使用して Maps JavaScript API を読み込む際に、await 演算子を使用して非同期関数内から importLibrary() を呼び出すことで、オプションで追加のライブラリを読み込むことができます。ライブラリは、メインの Maps JavaScript API に追加機能を提供するコードのモジュールですが、具体的にリクエストしない限り読み込まれません。詳しくは、Maps JavaScript API のライブラリをご覧ください。

地図の DOM 要素

<div id="map"></div>

地図をウェブページ上に表示するには、地図用の場所を確保する必要があります。通常、これは名前付きの div 要素を作成して、ブラウザのドキュメントオブジェクトモデル（DOM）内でこの要素への参照を取得することで行います。

上記のサンプルでは、CSS を使用して地図 div の高さを「100%」に設定しています。これにより、モバイルデバイスのサイズに合うように展開されるようになります。場合によっては、幅と高さの値をブラウザの画面サイズとパディングに応じて調節する必要があります。通常、div は含んでいる要素から幅を取得しますが、div が空の場合に高さは 0 になります。この理由から、<div> の高さは常に明示的に設定する必要があります。

地図のオプション

すべての地図には、center と zoom の 2 つの必須オプションがあります。

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

ズームレベル

地図を表示する初期解像度は、zoom プロパティを使用して設定されます。ズームが 0 は完全にズームアウトした地球の地図に相当し、ズームレベルの高さに応じて高い解像度にズームインします。

zoom: 8

地球全体の地図を単一の画像として指定すると、巨大な地図か、非常に低い解像度の小さな地図となってしまいます。そのため、Google マップおよび Maps JavaScript API 内の地図画像は、複数の地図タイルに分割され、複数のズームレベルで提供されます。低ズームレベルでは、少数の地図タイルのセットで広範囲をカバーし、高ズームレベルでは、高解像度のタイルで狭い範囲をカバーします。次のリストは、各ズームレベルで表示されるおおよその詳細度を示しています。

1: 世界
5: 大陸
10: 都市
15: 通り
20: 建物

次の 3 つの画像は、東京の同じ場所をそれぞれズームレベル 0、7、18 で表示したものです。

Maps JavaScript API が現在のズームレベルに基づいてタイルを読み込む仕組みの詳細については、地図とタイル座標のガイドをご覧ください。

地図オブジェクト

map = new Map(document.getElementById("map"), {...});

地図を表す JavaScript クラスは Map クラスです。このクラスのオブジェクトは、あるページ上の単一の地図を定義します（このクラスの複数のインスタンスを作成できます。各オブジェクトは特定のページ上の個別の地図を定義することになります）。このクラスの新しいインスタンスは、JavaScript の new 演算子を使用して作成します。

新しい地図インスタンスを作成するときに、地図のコンテナとしてページ内に <div> HTML 要素を指定します。HTML ノードは JavaScript document オブジェクトの子要素であり、document.getElementById() メソッドを使用してこの要素への参照を取得します。

このコードは、変数（名前は map）を定義して、その変数を新しい Map オブジェクトに渡します。関数 Map() はコンストラクタとして知られています。その定義を以下に示します。

コンストラクタ	説明
`Map(mapDiv:Node, opts?:MapOptions )`	渡される任意のパラメータを使用して（省略可）、指定された HTML コンテナ（通常は div 要素）内に新しい地図を作成します。

トラブルシューティング

API キーと請求エラー

場合によっては、「for development purposes only」という透かし入りの、暗い地図または白黒反転のストリートビュー画像が表示されることがあります。通常、これは API キーまたは請求の設定に問題があることを示しています。 Google Maps Platform サービスを使用するには、アカウントで課金を有効にし、すべてのリクエストに有効な API キーを含める必要があります。以下のフローに従って、この問題を解決してください。

API キーを使用していますか？

わかりません。API キーを使用しているかどうか、どのように確認すればよいですか？

API キーは、URL で key パラメータとして渡され、Maps JavaScript API を読み込むために使用されます。API キーを使用しているかどうかを確認するには、いくつかの方法があります。

Chrome 拡張機能の Google Maps Platform API Checker を使用します。このツールでは、Google から付与された Maps API がウェブサイトに適切に実装されているかどうか確認できます。
ライブラリまたはプラグインを使用して Maps JavaScript API を読み込む場合は、そのライブラリの設定で API キーのオプションを確認してください。
ブラウザでエラーを確認します。次のメッセージが表示された場合は、API キーを正しく使用していません。

Google Maps JavaScript API warning: NoApiKeys
Google Maps JavaScript API error: MissingKeyMapError

ウェブデベロッパー向け:

アプリケーションのソースコードにアクセスできる場合は、Maps JavaScript API の読み込みに使用される <script> タグを探します。Maps JavaScript API を読み込む際、以下のコードの YOUR_API_KEY をお客様の API キーに置き換えます。
```
  <script async defer
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap">
  </script>
```
お使いのブラウザで、ウェブサイトによって生成されたネットワークトラフィックを確認します。Chrome では、デベロッパーツールの [Network] タブを使用します。ここには、ウェブサイトから実行されたネットワークリクエストが表示されます。Maps JavaScript API を使用して実行されたリクエストは、パス maps/api/js の下に配置されます。ここでは、リクエストで key パラメータが使用されているかどうかを確認できます。[Network] タブを表示したとき、maps/api/js でネットワークトラフィックをフィルタリングすると便利です。

いいえ。API キーを使用していません。

下のボタンをクリックして、API キーを取得します。ガイド付きの設定手順が表示されない場合は、Google Maps Platform スタートガイドの手順に従ってください。
使ってみる

はい。API キーを使用しています。

では次に、請求先アカウントがプロジェクトにリンクされているか確認しましょう。

請求先アカウントがプロジェクトにリンクされていますか？

わかりません。請求先アカウントがプロジェクトにリンクされているかどうかを確認するには、どうすればよいですか？

Google Cloud Console の [お支払い] ページに移動し、API キーが作成されたプロジェクトを選択します。次の手順で、API キーがプロジェクトに関連付けられているかどうか確認します。

左側のナビゲーションバーで [Google Maps Platform] > [認証情報] を選択し、[認証情報] に移動します。
現在、ウェブサイトで使用している API キーが表示されていることを確認します。表示されない場合は、別のプロジェクトに切り替えて [認証情報] を確認します。
プロジェクトの認証情報に API キーが表示されない場合、そのプロジェクトにアクセスできなくなっている可能性があります。組織内の他のユーザーにサポートを依頼してください。元のプロジェクトが見つからない場合は、次の手順を実行します。
1. 新しいプロジェクトを作成します。そのためには、プロジェクトリストで [新しいプロジェクト] を選択するか、[リソースの管理] ページで [プロジェクトを作成] を選択します。
2. 新しい API キーを作成します。[認証情報] ページに移動し、[認証情報を作成] をクリックして、[API キー] を選択します。

Cloud Console で目的のプロジェクトを選択したら、左側のメニューで [お支払い] へ移動し、請求先アカウントがリンクされているかどうか確認します。

いいえ。請求先アカウントがプロジェクトにリンクされていません。

Cloud Console の [課金を有効にする] ページに移動し、プロジェクトに請求先アカウントを追加します。詳しくは、Google Maps Platform スタートガイドをご覧ください。

はい。プロジェクトに請求先アカウントがリンクされています。

では次に、設定したお支払い方法が有効かどうか確認しましょう。

設定したお支払い方法が無効になっていませんか（クレジットカードの期限切れなど）？

Cloud Console でお支払い方法の追加、削除、更新を行うことができます。

ご自身で設定した 1 日の API 使用量上限を超えていませんか？

使用量の予想外の増加に備え、API に 1 日あたりの上限を設定している場合、この上限を引き上げることで問題を解決できます。

1 日の上限は、Cloud Console の [API とサービス] ダッシュボードで確認できます。次の操作を行います。

確認のメッセージが表示されたら、プロジェクトを選択します。
リストから API を選択し、[割り当て] タブをクリックします。

API キーを特定の IP アドレスに制限していますか？

IP アドレスによる制限を設定している API キーは、サーバー側での使用を想定しているウェブサービス（Geocoding API やその他のウェブサービス API など）でのみ使用できます。これらのウェブサービスのほとんどは、Maps JavaScript API 内に同等のサービスがあります（Geocoding Serviceなど）。Maps JavaScript API クライアント側サービスを使用するには、別の API キーを作成し、HTTP リファラーによる制限で保護する必要があります（API キーの取得、追加、制限をご覧ください）。

コードが機能しない場合:

地図のコードが正常に動作するように、Brendan Kenny と Mano Marks はいくつかの一般的なミスとその修正方法をこの動画で指摘しています。

入力ミスを探します。JavaScript では大文字と小文字が区別されることに注意してください。
基本事項を確認します。よくある問題のいくつかは、地図の初期作成で発生します。次の点を確認してください。
- 地図のオプションで、zoom プロパティと center プロパティを指定していることを確認します。
- 地図を画面上で表示するための div 要素を宣言していることを確認します。
- 地図の div 要素に高さがあることを確認します。デフォルトでは、div 要素は高さ 0 で作成されるため非表示となります。
リファレンス実装のサンプルをご覧ください。
JavaScript Debugger（Chrome Developer Tools で使用できるものなど）を使用して、問題の特定に役立ててください。初めに、JavaScript コンソールでエラーを探します。
stackoverflow に質問を投稿します。効果的な質問の投稿方法のガイドラインについては、サポートページをご覧ください。

概要

対象読者

Hello World

TypeScript

JavaScript

CSS

HTML

サンプルを試す

Maps JavaScript API を読み込む

ブートストラップ ローダ

TypeScript

JavaScript

NPM js-api-loader パッケージ

TypeScript

JavaScript

アプリケーションを HTML5 として宣言する

Maps JavaScript API を読み込む

インライン読み込み

動的読み込み

動的読み込み

TypeScript

JavaScript

スクリプトタグ属性

ライブラリ

地図の DOM 要素

地図のオプション

ズームレベル

地図オブジェクト

トラブルシューティング

API キーと請求エラー

API キーを使用していますか？

わかりません。API キーを使用しているかどうか、どのように確認すればよいですか？

ウェブ デベロッパー向け:

いいえ。API キーを使用していません。

はい。API キーを使用しています。

請求先アカウントがプロジェクトにリンクされていますか？

わかりません。請求先アカウントがプロジェクトにリンクされているかどうかを確認するには、どうすればよいですか？

いいえ。請求先アカウントがプロジェクトにリンクされていません。

はい。プロジェクトに請求先アカウントがリンクされています。

設定したお支払い方法が無効になっていませんか（クレジットカードの期限切れなど）？

ご自身で設定した 1 日の API 使用量上限を超えていませんか？

API キーを特定の IP アドレスに制限していますか？

コードが機能しない場合:

ブートストラップローダ

ウェブデベロッパー向け: