Google Maps API

マップ API

マプレット API
- ホームページ
- ドキュメント

Google マップ API の概念

Google マップ API デベロッパーガイドにようこそ。Google Maps JavaScript API を使用すると、皆さんのウェブページにも Google マップを埋め込むことができます。この API を使用するには、まず API キーを取得してください。API キーを取得したら、このガイドの指示に従って地図アプリケーションを開発できます。

Google マップ API は、複数の Google AJAX API を読み込んで使用するための共通フレームワークを作成する Google AJAX API ローダーに統合されています。詳細については、下記の情報を参照してください。

Google マップ API での Google AJAX API ローダーの使用
Google AJAX API ドキュメント

New! Google マプレット - Google マップサイトに組み込むミニアプリケーションを作成。

対象読者

このガイドは、JavaScript のプログラミング概念とオブジェクト指向プログラミングの概念を理解しているデベロッパーを対象にしています。また、Google マップを使ったことがあり、ユーザーの観点からこのサービスを理解している必要もあります。ウェブ上では多くの JavaScript チュートリアルが公開されています。

このガイドはコンセプトを説明しており、すべての情報を網羅しているわけではありません。Google マップ API を使用して魅力的なアプリケーションの設計と開発をすばやく開始できるように支援することを目的としています。比較的詳しい情報が記載された Google マップ API リファレンスも併せてご覧ください。

このドキュメントではまずコンセプトを理解できるよう、次のようなトピックに分かれています。

マップ API を初めて利用する方にもわかりやすいような構成になっています。このドキュメントに関するご意見もぜひお寄せください。マップ API に関するご意見がありましたら、マップ API デベロッパーヘルプグループにご参加ください。デベロッパー同士で情報交換もできます。

Google マプレットの作成

Google マップ API で新たにサポートされたマプレット (Mapplet、マップ + ガジェット) を使用すると、外部で提供されているアプリケーションを Google マップ内に組み込むことができます。これらのマプレットは独自の iFrame 内で実行され、ユーザーは「マッシュアップのマッシュアップ」を作成して、たとえば2つのサイトのコードを組み合わせることができます。これにより、Google マップ内でのまったく新しいコーディング環境が得られます。マプレットは簡単に作成できますが、いくつかの作業は標準の Google マップ API の場合とは異なる方法で行います。詳細については、Google マップのマプレットドキュメントとリファレンスを参照してください。

Google AJAX API ローダーの使用

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

Google AJAX API フレームワークの使用は比較的シンプルです。このフレームワークを使用するようにアプリケーションを変更する方法は次のとおりです。

この API を http://maps.google.com/apis から読み込む代わりに、共通ローダーを http://www.google.com/jsapi から読み込みます。既存の Google マップ API キーは次の URL に渡すことができます。
```
<script type="text/javascript" src="http://www.google.com/jsapi?key=ABCDEFG"></script>
```
希望する特定の API を google.load メソッドを使用して読み込みます。google.load メソッドは、読み込む API の名前とバージョン番号の引数をとります。
```
<script type="text/javascript">
  google.load("maps", "2");
</script>
```

Google マップ API で現在使用しているすべてのクラス、メソッド、プロパティ用に google.maps.* 名前空間を使用して、G プレフィックスをこの名前空間で置き換えます。オブジェクトの初期化には、google.setOnLoadCallback() を使用します。たとえば Google AJAX API ローダーの使用時は、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");
   
// ページが読み込まれたときにこの関数を呼び出します
  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 ローダーの使用詳細については、http://code.google.com/apis/ajax/documentation/ を参照してください。

プログラミングに関する注記

Google マップ API の使用を開始する前に、次の注意事項を参照して、作成するアプリケーションがすべての対象プラットフォームで正常に動作することを確認してください。

ブラウザの互換性

Google マップ API は、Google マップのサイトと同じブラウザをサポートしています。このスクリプト http://maps.google.com/maps?file=api&v=2 はほぼすべてのブラウザでエラーなく解析できるため、互換性をチェックする前にこのスクリプトを問題なく組み込むことができます。

互換性のないブラウザを使用するユーザーには、アプリケーションごとに異なる動作を実装することが必要になる場合があります。マップ API は、互換性をチェックするためのグローバルメソッド (GBrowserIsCompatible()) を提供していますが、互換性のないブラウザを検出したときの自動動作は用意されていません。このドキュメント内のほとんどの例では、ブラウザの互換性はチェックされず、古いブラウザに対してエラーメッセージが表示されることもありません。実際のアプリケーションでは、互換性のないブラウザについてはなんらかの便宜上の処理が行われるはずですが、このドキュメントでは例を簡潔にするためにこのようなチェック処理は省略しています。

複雑なアプリケーションでは、ブラウザとプラットフォーム間の不整合が必然的に発生します。これらの問題に対する簡単な解決策はありませんが、Google マップ API デベロッパーヘルプグループと quirksmode.org はどちらも対処法を見つけるのに役立つサイトです。

XHTML と VML

地図が掲載されたページでは、標準に準拠した XHTML を使用することをお勧めします。ブラウザは、ページの先頭で XHTML の DOCTYPE 宣言を検知すると、そのページを「標準準拠モード」で表示し、その結果として各種のブラウザでそのページのレイアウトと動作の予測可能性が大幅に高まります。この宣言のないページは、下位互換モード (Quirks Mode)で表示されることがあり、結果として一貫性のないレイアウトになる可能性があります。

地図上でポリライン (Google マップで運転ルートの表示に使う線など) を表示するには、XHTML ドキュメントに VML 名前空間を組み込んで 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 URL 内の v パラメータは、使用する Google マップ API のバージョン番号を表しています。マップ API のほとんどのユーザーは、この URL 内で v=2 パラメータを渡して現在の「バージョン2」API を使用することをお勧めします。代わりに、v=2.x パラメータを渡して最新リリース (最新機能を含む) を取得することもできます。ただし、最新リリースは v=2 リリースより信頼性が劣る場合があるのでご注意ください。Google マップ API は頻繁に (場合によっては毎週) 更新され、更新時には問題が発見されない限り v=2.x リリースの機能が v=2 リリースに取り込まれます。

さらに、v=2.s パラメータを渡すことで「安定」バージョンの API を使用できます。このバージョンは更新頻度が低く、およそ数か月ごとに更新されます。v=2 リリースと v=2.x リリースはおよそ2週間ごとに更新されるため、安定した v=2.s を優先的に使っていらっしゃる方もいるようです。安定バージョンは現行バージョンより数バージョン古いことがあるため、一部の最新機能を含んでいない可能性があります。

API の各バージョンは、更新されるたびに番号が割り当てられます (「バージョン2.76」など)。API が更新された場合、以前のバージョンに基づいた古いコードは公表されているとおりに動作しないことがあります。アプリケーションで特定バージョンの API を使用する必要がある場合は、そのバージョンを v パラメータで指定してください (例: v=2.75)。ただしこの方法はお勧めしません。更新されたコードをプロダクトのベースにすることが常に理想的です。

今後 API を大幅に更新する場合は、メジャーバージョン番号を更新して、Google Code とマップ API デベロッパーヘルプグループに通知を掲載します。その場合は、コードを移行するための猶予期間として1か月以上は両方のバージョンをサポートする予定です。

Maps チームは、最新のバグフィックスやパフォーマンス強化で API を透過的に更新することもあります。これらのバグフィックスはパフォーマンス向上とバグ修正のみを目的としていますが、意図せずに一部の API クライアントに障害をもたらす可能性があります。このような問題を発見されましたら、マップ API デベロッパーヘルプグループからお知らせください。

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

このドキュメントでは、2006年4月3日に公開されたマップ API のバージョン2について述べています。API にマップ API のバージョン1を使用している場合 (2006年4月3日より前にサイトを作成した場合) は、ウェブサイトをアップグレードしてみてください。詳細については、バージョン2アップグレードガイドを参照してください。

マップ API 内の例

このドキュメント内のほとんどの例では、HTML ファイル全体ではなく関連する JavaScript コードのみを表示しています。これらの JavaScript コードを各自のスケルトン HTML ファイルに挿入することも、例の後のリンクをクリックして各例の HTML ファイル全体をダウンロードすることもできます。

ブラウザのメモリリークを防止

Google マップ API では関数クロージャの使用を推奨しています。API イベントハンドルシステムの GEvent による DOM ノードへのイベントの添付方法では、Internet Explorer などの一部のブラウザで、高い確立でメモリリークが発生してしまいます。マップ API のバージョン2で導入された新しいメソッドの GUnload() によって、これらのメモリリークの原因となる循環参照のほとんどが解消されます。作成したページの onunload イベントで次のように GUnload() を呼び出して、アプリケーションでメモリリークが発生する可能性を低減させてください。

<body onunload="GUnload()">

この機能を使用すると、Google マップでの Internet Explorer のメモリリークをほぼ回避できますが、メモリ消費の問題が見受けられる場合は Drip などのツールを使用して各自のサイトでメモリリークが発生していないか調べてください。

他の参考情報

いくつかの参考情報 (英語) を以下に紹介します。なお、これらのサイトは、Google が作成またはサポートしているものではありません。

Google Mapki:Mapki
Google Maps API Tutorial:http://www.econym.demon.co.uk/googlemaps/
Esa's Google Maps API Examples: http://koti.mbnet.fi/ojalesa/exam/index.html
USNaviguide's Maps API Examples:http://maps.huge.info/examples.htm
Mark McClure's Encoded Polyline Examples: http://facstaff.unca.edu/mcmcclur/GoogleMaps/EncodePolyline/
Marcelo's Maps API Experiments:http://maps.forum.nu/
Bill Chadwick's Maps API Demos:http://www.bdcc.co.uk/Gmaps/BdccGmapBits.htm

トラブルシューティング

作成したコードが正常に機能しない場合は、次の方法によって問題を解決してみてください。

API キーが有効であることを確認します。
タイプミスがないか確認します。JavaScript では大文字と小文字が区別されます。
JavaScript デバッガを使用します。Firefox では、JavaScript コンソール、Venkman Debugger、Firebug アドオンのいずれかを使用できます。 IE では、Microsoft Script Debugger を使用できます。
マップ API デベロッパーヘルプグループで解決策を探します。お探しの情報が見つからない場合は、グループに質問を投稿して、問題のページへのリンクを添えてください。
外部サイトからの情報も参考にしてみてください。


例: "ajax apis" または "open source"