概要

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

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

対象読者

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

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

Hello World

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

TypeScript

let map: google.maps.Map;

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

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;
index.ts

JavaScript

let map;

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

window.initMap = 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>

    <!--
      The `defer` attribute causes the callback to execute after the full HTML
      document has been parsed. For non-blocking uses, avoiding race conditions,
      and consistent behavior across browsers, consider loading using Promises
      with https://www.npmjs.com/package/@googlemaps/js-api-loader.
      -->
    <script
      src="https://maps.googleapis.com/maps/api/js?key=AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg&callback=initMap&v=weekly"
      defer
    ></script>
  </body>
</html>
index.html
サンプルを表示

サンプルを試す

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

  1. <!DOCTYPE html> 宣言を使用して、アプリケーションを HTML5 として宣言しています。
  2. 地図を保持する「map」という名前の div 要素を作成しています。
  3. div 内に地図を作成する JavaScript 関数を定義しています。
  4. script タグを使用して Maps JavaScript API を読み込みんでいます。

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

アプリケーションを 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(() => {
  map = new google.maps.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(() => {
  map = new google.maps.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 を読み込むときに、オプションで libraries URL パラメータを使用して、追加のライブラリを読み込めます。ライブラリは、メインの Maps JavaScript API に追加機能を提供するコードのモジュールですが、具体的にリクエストしない限り読み込まれません。詳しくは、Maps JavaScript API のライブラリをご覧ください。

API を同期的に読み込む

Maps JavaScript API を読み込む script タグ内では、defer 属性と callback パラメータを省略できます。省略すると、API がダウンロードされるまで API の読み込みがブロックされます。

これにより、多くの場合ページ読み込みが低速になりますが、API がすでに読み込まれていると想定して後続のスクリプトタグを記述できるようになります。

地図の DOM 要素

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

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

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

地図のオプション

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

map = new google.maps.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 google.maps.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 キーを含める必要があります。以下のフローに従って、この問題を解決してください。

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

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

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