お気に入り | 日本語 | ログイン

Google Maps API の概念

Google Maps API デベロッパー ドキュメントにようこそ。Google Maps JavaScript API を使用すると、Web ページに Google マップを埋め込むことができます。API を使用するには、まず API キーを取得する必要があります。API キーを取得したら、このドキュメントに記載されている手順に沿って、地図アプリケーションを開発できます。

New! Maps API の逆ジオコーディングにサポートが提供されます。

目次

  1. 対象読者
  2. Google マプレットを作成
  3. Google AJAX API ローダーを使用
  4. Google Maps API のローカライズ
  5. センサー パラメータを指定する New!
  6. プログラムに関する注意事項
    1. ブラウザの互換性
    2. XHTML と VML
    3. API のアップデート
    4. Google Maps v1 アプリケーションのアップグレード
    5. メモリ リークの防止
  7. トラブルシューティング
  8. その他のリソース

対象読者

このドキュメントは JavaScript プログラミングとオブジェクト指向プログラミングの概念に精通している方を対象としています。また、Google マップの使用方法をユーザーとしてよく理解している必要があります。Web 上では、多数の JavaScript チュートリアルが公開されています。

このドキュメントでは概念のみを扱っています。Google Maps API を使ったアプリケーションの研究と開発を簡単に始めていただけることを目的としており、すべての情報を網羅しているわけではありません。より詳細な情報については、Google Maps API リファレンスをご覧ください。

先ごろこのドキュメントの改訂を行い、次の主な領域についてより概念的な情報と、発展的なディスカッションを追加しました。

改訂により、特に Maps API の開発経験がない方にとって、情報が見つけやすくなっていれば幸いです。本ドキュメントに対するご意見やご感想もお待ちしております。Maps API デベロッパー フォーラムで、API に対するフィードバックやディスカッションにもご参加ください。

Google マプレットの作成

Google Maps API がマプレット (マップ + ガジェット) に対応しました。これにより、Google マップ内に外部サイトでホストされているアプリケーションを埋め込むことができるようになります。マプレットはそれ自身の iFrames 内で動作し、「マッシュアップのマッシュアップ」を作成したり、さまざまなサイトのコードを混ぜ、例として使用したりすることができます。これにより、Google マップでのコーディングの幅が、さらに広がることでしょう。マプレットの作成は簡単ですが、一部、標準的な Google Maps API とは異なる点があります。詳しくは、Google マップのマプレット ドキュメントとリファレンスをご覧ください。

Google AJAX API Loader の使用

Google Maps API は、Google AJAX API と完全に統合されました。このフレームワークにより、サポートされているすべての Google AJAX API (Google マップも含む) に対して 1 つの API キーを読み込むことができ、さらに各 API に共通の名前空間を提供できるため、異なる Google API をまとめて操作することができます。Google AJAX API のフレームワークを使用しない場合でも、既存の名前空間を引き続き使用できます。

Google AJAX API フレームワークの使用は、比較的シンプルです。次の手順で使用するアプリケーションを変更できます。

  • http://maps.google.com/apis から API を読み込む代わりに、http://www.google.com/jsapi から共通ローダーを読み込みます。既存の Google Maps API キーを次の URL に渡すことができます。 
    <script type="text/javascript" src="http://www.google.com/jsapi?key=ABCDEFG"></script>
  • google.load メソッドを使用して特定の API を読み込みます。google.load メソッドを読み込むには、特定の API とバージョン番号を示す引数を取ります。 
    <script type="text/javascript">
  google.load("maps", "2");
</script>
  • 現在 Google Maps API で使用しているすべてのクラス、メソッド、プロパティで google.maps.* 名前空間を使用します。接頭辞 G の部分をこの名前空間で置き換えます。google.setOnLoadCallback() を使用して、すべてのオブジェクトの初期化を行います。たとえば、Google AJAX API Loader を使う場合には GMap2 オブジェクトは google.maps.Map2 にマップされます。 
    <script type="text/javascript" src="http://www.google.com/jsapi?key=ABCDEFG"></script>
<script type="text/javascript">
  google.load("maps", "2.x");
   
  // Call this function when the page has been loaded
  function initialize() {
    var map = new google.maps.Map2(document.getElementById("map"));
    map.setCenter(new google.maps.LatLng(37.4419, -122.1419), 13);
  }
  google.setOnLoadCallback(initialize);
</script>

Google AJAX API Loader の使用に関する詳しいドキュメントは http://code.google.com/apis/ajax/documentation/ にあります。

Google Maps API のローカライズ

Google Maps API は、コントロール名、著作権情報、ルート案内などのテキストの情報を表示するとき、ブラウザで設定された言語を使用します。Maps API がブラウザの言語設定を無視して、特定の言語で表示するように変更したい場合は、Maps API の JavaScript コードを組み込むときに任意の hl パラメータを <script> タグに追加して、使用するドメイン言語を指定します。

たとえば、Maps API アプリケーションをドイツ語で表示するには、次のように &hl=de を <script> タグに追加します。

<script type="text/javascript" src="http://maps.google.com/maps?file=api&v=2&key=abcdefg&hl=de"

サポートされているドメイン言語のリストもご覧ください。サポートされている言語は随時更新されているため、このリストは最新ではない場合があります。

センサー パラメータを指定する

Google Maps API を使用する際には、アプリケーションがユーザーの位置情報を取得するのにセンサー（GPS など）を使用するかどうかを示す必要があります。これは携帯端末では特に重要です。アプリケーションは Maps API の JavaScript コードを組み込むときに要求された sensor パラメータを <script> タグに渡し、アプリケーションがセンサー装置を使用しているかどうかを示す必要があります。

センサーを経由してユーザー位置情報を取得するアプリケーションは、http://maps.google.com/maps または共通ローダーを使用して Maps API JavaScript を読み込む際に &sensor=true を渡す必要があります。

#
# Example using sensor when loading the Maps JavaScript API
#
<script type="text/javascript" src="http://maps.google.com/maps?file=api&v=2&key=abcdefg&sensor=true">
#
# Example using sensor when loading the Maps API via the common loader
#
<script type="text/javascript" src="http://www.google.com/jsapi?key=abcdef"></script>
<script type="text/javascript">
  google.load("maps", "2",{"other_params":"sensor=true"});

  function initialize() {
    var map = new google.maps.Map2(document.getElementById("map"));
    map.setCenter(new google.maps.LatLng(37.4419, -122.1419), 13);
  }
  google.setOnLoadCallback(initialize);
</script>

アプリケーションがセンサー装置を使用していない場合でもこのパラメータは値を false に設定して渡さなければなりません。

プログラムに関する注意事項

Google Maps API の開発を始める前に、次の注意事項をよく読んで、意図するプラットフォーム上でアプリケーションが問題なく動作することを確認してください。

ブラウザの互換性

Google Maps API は、Google マップ Web サイト対応ブラウザに対応しています。スクリプト「http://maps.google.com/maps?file=api&v=2」は、ほぼすべてのブラウザでエラーなしで解析されるため、互換性を確認せずに使用することができます。

互換性のないブラウザを使用しているユーザーのために必要な動作は、アプリケーションによって異なる場合があります。Maps API ではグローバル メソッド (GBrowserIsCompatible()) を提供して互換性の確認を行います。ただし、互換性のないブラウザを検知した場合に自動的になんらかの動作を行うことはありません。このドキュメントに掲載されている例のほとんどでは、ブラウザ互換性の確認は行われません。また、古いブラウザに対してエラー メッセージが表示されることもありません。もちろん、実際のアプリケーションでは、互換性のないブラウザにやさしい動作が必要ですが、わかりやすくするために例からはそのような確認を省いています。

ブラウザとプラットフォームの非互換性は、ある程度の大きさのアプリケーションでは避けられない問題です。この問題を解決するシンプルな方法はありませんが、回避方法については Google Maps API デベロッパー フォーラムと quirksmode.org で役に立つ情報を参照できます。

XHTML と VML

地図を含むページでは、標準準拠の XHTML を使用することをお勧めします。ブラウザにより、ページ上部にある XHTML DOCTYPE が検出されると、「標準準拠モード」でページのレンダリングが行われます。これにより、レイアウトや動作をブラウザにかかわらず、より正確に予測できるようになります。この宣言がないページは「下位互換モード」でレンダリングされ、ブラウザごとにレイアウトが異なる原因となる場合があります。

ポリライン (たとえば、Google マップで運転経路の表示に使用されているライン) を地図上に表示する場合は、VML 名前空間を XHTML ドキュメントに含めて、Internet Explorer 上ですべてが正しく動作するようにする必要があります。XHTML ドキュメントの開始部分は、次のようにする必要があります。

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xmlns:v="urn:schemas-microsoft-com:vml">

API のアップデート

http://maps.google.com/maps?file=api&v=2 内の v パラメータは、使用する Google Maps API のバージョン番号を参照します。ほとんどの API ユーザーには、この URL 内で v=2 パラメータを渡し、現行の API バージョン 2 を使用することをお勧めします。代わりに v=2.x を渡して、最新の機能を含む、最新リリースを取得することもできます。ただし、最新リリースは信頼性のうえで v=2 リリースに劣る場合があることに注意してください。Google Maps API は頻繁に (毎週の場合もあります) 更新されています。更新時に特に問題がない限り、v=2.x リリース内の機能は v=2 リリースに移行されます。

また、v=2.s パラメータを渡すことによって、「安定」バージョンの API を使用できます。このバージョンの更新頻度は低く、およそ数か月に 1 回です。v=2 リリースと v=2.x リリースはおよそ 2 週間に 1 度更新されるため、デベロッパーの中には安定した v=2.s の使用を好む方もいます。安定バージョンは現行バージョンよりも数バージョン古く、そのため最新機能がすべて含まれているわけではないことに留意してください。

API のバージョンについては、更新時に明記されます（例: バージョン 2.76）。API が更新されると、以前のバージョンに基づく古いコードで、公表されている動作が行われなくなる場合があります。作成したアプリケーションで、特定のリリースの API を使用するには、v パラメータ内に指定のバージョンを明示的に含めます（例: v=2.75）。ただし、この方法は推奨されません。アプリケーションでは、随時更新されたコードを使用するようにするのが理想的です。

今後 API に重大な更新を行う場合は、メジャー バージョン番号を変更し、Google Code と Maps API デベロッパー フォーラムで、その旨をお知らせいたします。この場合には、ユーザーがコードを移行できるようにするため、最低 1 か月間は両方のバージョンをサポートします。

Maps チームではまた、最新のバグ修正とパフォーマンス向上のための API の更新を透過的に行っています。これにより、パフォーマンスの向上とバグの修正が行われますが、API クライアントの一部に思わぬ障害が生じる恐れがあります。このような問題を見つけた場合は、Maps API デベロッパー フォーラムでご報告ください。

v1 アプリケーションのアップグレード

このドキュメントは 2006 年 4 月 3 日にリリースされた Maps API のバージョン 2 に基づくものです。お使いの API が Maps API バージョン 1 の場合、または、2006 年 4 月 3 日より前に開発されたサイトの場合は、Web サイトをアップグレードしてください。詳しくは、バージョン 2 アップグレード ガイドをご覧ください。

Maps API の例

このドキュメントに記載されている例のほとんどは、関連する JavaScript コードのみを記載しており、HTML ファイル全体が記載されているわけではありません。スケルトン HTML ファイルに JavaScript コードをプラグインするか、例の最後に表示されているリンクをクリックして、各例の HTML ファイル全体をダウンロードすることができます。

ブラウザのメモリ リークの削減

Google Maps API では、関数クロージャの使用を推奨しています。API イベント ハンドル システムである GEvent が DOM ノードにイベントを添付する場合、一部のブラウザ (特に Internet Explorer) でほぼ確実にメモリ リークを引き起こします。Maps API バージョン 2 では新しいメソッドである GUnload() を導入することにより、リークの原因となる循環参照のほとんどが解消されます。自分のページの onunload イベントで GUnload() を呼び出し、アプリケーションでメモリ リークが発生するリスクを軽減してください。

<body onunload="GUnload()">

この機能を使用すると、Internet Explorer で Google マップを使用した際のメモリ リークをほぼ確実に回避できます。ただし、メモリ消費の問題がある場合には、Drip などのツールを使用して自分のサイトでメモリ リークが発生していないかどうかを確認する必要があります。

その他のリソース

次にご紹介する、その他のリソースも参照してください。これらのサイトは Google が所有およびサポートしているものではありません。

トラブルシューティング

コードが正しく動作していない場合、次の解決方法をお試しください。

  • 使用している API キーが有効であることを確認します。
  • ミスタイプがないかどうかを確認します。JavaScript では大文字と小文字が区別されるため、正しく記述されていることを確認します。
  • JavaScript デバッガを使用します。Firefox では、JavaScript コンソール、Venkman Debugger や Firebug アドオンのいずれかを使用できます。IE の場合は Microsoft Script Debugger を使用できます。このスクリーンショットでは、さまざまなデバッグ用ツールの使用方法をご紹介しています。
  • Maps API デベロッパー フォーラムで、解決方法を検索します。疑問に対する答えが投稿されていない場合は、問題を具体的に示している Web ページへのリンクを含めて、グループに質問を投稿してください。
  • その他のリソースで、サードパーティのデベロッパー リソースも参照してください。