注意: 一部のページは英語でのみご利用いただけます。
企業向けのライセンスとサポートが含まれます
サービス
サービスの概要
Google マップ API は新しい機能の追加によって定期的に拡張されています。多くの場合、こうした機能はmaps.google.com で最初にリリースされます。このセクションでは、次のサービスについて説明します。注: 「サービス」の定義はわかりにくいため、このセクションはやや包括的な内容となっています。基本的に、このセクションには他で説明できなかったことがまとめられています。
XML とデータ解析
Google マップ API は、最新バージョンの Internet Explorer、Firefox、Safari で動作するブラウザに依存しない XmlHttpRequest() オブジェクトを作成するためのファクトリ メソッドをエクスポートします。すべての XmlHttpRequest と同様に、取得されたファイルはローカル ドメイン上にある必要があります。次の例では、myfile.txt という名前のファイルをダウンロードし、その内容を JavaScript alert() で表示します。
var request = GXmlHttp.create();
request.open("GET", "myfile.txt", true);
request.onreadystatechange = function() {
if (request.readyState == 4) {
alert(request.responseText);
}
}
request.send(null);
また、API は XmlHttpRequest() readyState のチェックを不要にする、一般的な HTTP GET 要求用のより単純な GDownloadUrl() メソッドもエクスポートします。上記の例は、GDownloadUrl() を使用して次のように書き換えることができます。
GDownloadUrl("myfile.txt", function(data, responseCode) {
alert(data);
});
静的メソッド GXml.parse() で XML ドキュメントを解析できます。このメソッドは、XML の文字列を唯一の引数として受け取ります。このメソッドは、最新のブラウザのほとんどと互換性がありますが、ブラウザが XML 解析をネイティブにサポートしていない場合は例外をスローします。
次の例では、GDownloadUrl メソッドを使用して、緯度と経度の座標のリストを含む静的な XML ファイル ("data.xml") をダウンロードします。ダウンロードが完了したら、GXml を使用して XML を解析し、XML ドキュメント内の各地点にマーカーを作成します。
var map = new GMap2(document.getElementById("map_canvas"));
map.addControl(new GSmallMapControl());
map.addControl(new GMapTypeControl());
map.setCenter(new GLatLng(37.4419, -122.1419), 13);
// data.xml のデータをダウンロードし、地図上に読み込みます。予期される形式は
// 次のとおりです。
// <markers>
// <marker lat="37.441" lng="-122.141"/>
// <marker lat="37.322" lng="-121.213"/>
// </markers>
GDownloadUrl("data.xml", function(data, responseCode) {
var xml = GXml.parse(data);
var markers = xml.documentElement.getElementsByTagName("marker");
for (var i = 0; i < markers.length; i++) {
var point = new GLatLng(parseFloat(markers[i].getAttribute("lat")),
parseFloat(markers[i].getAttribute("lng")));
map.addOverlay(new GMarker(point));
}
});
例を表示 (xhr-requests.html)。この例では、外部 XML データ ファイル data.xml を使用しています。
詳細については、GXmlHttp クラス参照と GXml クラス参照をご覧ください。
ジオコーディング
ジオコーディングとは、住所 (「1600 Amphitheatre Parkway, Mountain View, CA」など) を地理座標 (緯度 37.423021、経度 -122.083739 など) に変換する処理のことです。ジオコーディングを使用して、マーカーを配置したり、地図の位置を指定することができます。Google マップ API は、HTTP 要求を経由して直接アクセスするか、または GClientGeocoder オブジェクトを使用してアクセスできるジオコーディング サービスを備えています。
ジオコーディングは時間とリソースを消費するタスクです。住所はできるだけ事前に (HTTP ジオコーダまたはその他のジオコーディング サービスを使用して) ジオコーディングし、ジオコード キャッシュ を使用して結果を格納しておいてください。
HTTP 要求経由のジオコーディング
サーバー側スクリプトを使用してマップ API ジオコーダに直接アクセスするには、URI に次のパラメータを指定して http://maps.google.com/maps/geo? に要求を送信します。
q-- ジオコーディングする住所。key-- API キー。output-- 生成される出力の形式。xml、kml、csv、またはjsonを指定できます。
次の例では、Google US 本社の地理座標を要求します。
http://maps.google.com/maps/geo?q=1600+Amphitheatre+Parkway,+Mountain+View,+CA&output=xml&key=abcdefg
出力に json を指定した場合、応答は JSON オブジェクト形式になります。xml または kml を指定した場合、応答は KML 形式で返されます。XML 出力と KML 出力は MIME の種類を除いて同じです。
たとえば、ジオコーダで「1600 amphitheatre mountain view ca」に対して返される応答は次のようになります。
<kml xmlns="http://earth.google.com/kml/2.0">
<Response>
<name>1600 amphitheatre mountain view ca</name>
<Status>
<code>200</code>
<request>geocode</request>
</Status>
<Placemark>
<address>
1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA
</address>
<AddressDetails Accuracy="8">
<Country>
<CountryNameCode>US</CountryNameCode>
<AdministrativeArea>
<AdministrativeAreaName>CA</AdministrativeAreaName>
<SubAdministrativeArea>
<SubAdministrativeAreaName>Santa Clara</SubAdministrativeAreaName>
<Locality>
<LocalityName>Mountain View</LocalityName>
<Thoroughfare>
<ThoroughfareName>1600 Amphitheatre Pkwy</ThoroughfareName>
</Thoroughfare>
<PostalCode>
<PostalCodeNumber>94043</PostalCodeNumber>
</PostalCode>
</Locality>
</SubAdministrativeArea>
</AdministrativeArea>
</Country>
</AddressDetails>
<Point>
<coordinates>-122.083739,37.423021,0</coordinates>
</Point>
</Placemark>
</Response>
</kml>
複数の結果、整形された形式などの特別な機能は不要で、解析しやすい短い応答を希望する場合は、csv 出力も用意されています。csv 形式で返される応答は、コンマで区切られた 4 つの数字で構成されます。
- HTTP 状態コード
- 精度 (「 精度定数」を参照)
- 緯度
- 経度
次の例は、3 つの住所に対する応答を精度の低い方から順に示しています。住所は「State St, Troy, NY」、「2nd st & State St, Troy, NY」、「7 State St, Troy, NY」の 3 つです。
200,6,42.730070,-73.690570 200,7,42.730210,-73.691800 200,8,42.730287,-73.692511
ジオコーディング オブジェクト
Google マップ API ジオコーダには、GClientGeocoder オブジェクト経由でアクセスすることもできます。 GClientGeocoder.getLatLng() を使用して住所の文字列を GLatLng に変換します。このメソッドは、変換する住所の文字列と住所の取得時に実行されるコールバック関数を、パラメータとして取ります。ジオコーディングでは要求を Google のサーバーに送信する必要があるため、コールバック関数が必要となります。これには時間がかかる場合があります。
次の例では、住所をジオコーディングし、その地点にマーカーを追加し、住所を表示した情報ウィンドウを開きます。コールバックは関数リテラルとして渡されます。
var map = new GMap2(document.getElementById("map_canvas"));
var geocoder = new GClientGeocoder();
function showAddress(address) {
geocoder.getLatLng(
address,
function(point) {
if (!point) {
alert(address + " not found");
} else {
map.setCenter(point, 13);
var marker = new GMarker(point);
map.addOverlay(marker);
marker.openInfoWindowHtml(address);
}
}
);
}
GClientGeocoder.setViewport() メソッドを通じて、指定されたビューポート内 (タイプ GLatLngBounds の境界ボックスで表現) の結果を優先するようにマップ API ジオコーダを変更することもできます。GClientGeocoder.setBaseCountryCode() メソッドを使用すると、特定のドメイン (国) に合わせた結果を返すことができます。ジオコーディング要求は、Google Maps のメイン アプリケーションでジオコーディングが提供されているすべてのドメインに対して送信できます。たとえば、「トレド」を検索した場合、国コード「es」で指定されたスペインのドメイン (http://maps.google.es) 内では、米国内のデフォルトのドメイン (http://maps.google.com) とは異なった結果が返されます。
構造化された住所の抽出
住所に関する構造化された情報にアクセスしたい場合、GClientGeocoder には次の情報で構成される JSON オブジェクトを返す getLocations() メソッドも用意されています。
Status-
request-- 要求の種類。この場合は常にgeocodeです。code-- ジオコード要求が成功したかどうかを示す応答コード (HTTP 状態コードと同様)。 状態コードの完全なリスト を参照してください。
Placemark-- ジオコーダで複数の一致が見つかった場合は、複数の目印が返されることがあります。-
address-- 整形され、適切に大文字に変換された形式の住所。AddressDetails-- 住所の表記形式の国際的な標準である xAL (eXtensible Address Language) 形式の住所。-
Accuracy-- 指定された住所のジオコードの精度を示す属性。考えられる値のリスト を参照してください。
Point-- 3D 空間における地点。-
coordinates-- 住所の緯度、経度、高度。この場合、高度は常に 0 に設定されます。
以下に、Google 本社の住所に対してジオコーダで返された JSON オブジェクトを示します。
{
"name": "1600 Amphitheatre Parkway, Mountain View, CA, USA",
"Status": {
"code": 200,
"request": "geocode"
},
"Placemark": [
{
"address": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
"AddressDetails": {
"Country": {
"CountryNameCode": "US",
"AdministrativeArea": {
"AdministrativeAreaName": "CA",
"SubAdministrativeArea": {
"SubAdministrativeAreaName": "Santa Clara",
"Locality": {
"LocalityName": "Mountain View",
"Thoroughfare": {
"ThoroughfareName": "1600 Amphitheatre Pkwy"
},
"PostalCode": {
"PostalCodeNumber": "94043"
}
}
}
}
},
"Accuracy": 8
},
"Point": {
"coordinates": [-122.083739, 37.423021, 0]
}
}
]
}
次の例では、getLocations() メソッドを使用して住所をジオコーディングし、整形された形式の住所と 2 文字の国名を JSON から抽出して、情報ウィンドウに表示します。
var map;
var geocoder;
function addAddressToMap(response) {
map.clearOverlays();
if (!response || response.Status.code != 200) {
alert("\"" + address + "\" not found");
} else {
place = response.Placemark[0];
point = new GLatLng(place.Point.coordinates[1],
place.Point.coordinates[0]);
marker = new GMarker(point);
map.addOverlay(marker);
marker.openInfoWindowHtml(place.address + '<br>' +
'<b>Country code:</b> ' + place.AddressDetails.Country.CountryNameCode);
}
}
例を表示 (geocoding-extraction.html)
ジオコーディングのキャッシュ
GClientGeocoder には、デフォルトでクライアント側キャッシュが組み込まれています。キャッシュにはジオコーダの応答が格納され、住所が再びジオコーディングされた場合に応答にかかる時間を短縮できます。GClientGeocoder オブジェクトの setCache() メソッドに null を渡すことで、キャッシュをオフにできます。ただし、キャッシュによりパフォーマンスが向上するため、キャッシュはオンのままにすることをお勧めします。GClientGeocoder で使用されているキャッシュを変更するには、setCache() を呼び出して新しいキャッシュを渡します。現在のキャッシュの内容を空にするには、ジオコードに対して、または直接キャッシュに対して reset() メソッドを呼び出します。
独自のクライアント側キャッシュを構築することをお勧めします。次の例では、ジオコーディング API の対象となっている国の 6 つの首都について、ジオコーダによる事前に計算された応答を含むキャッシュを構築します。まず、ジオコードの応答の配列を構築します。次に、標準の GeocodeCache を拡張したカスタム キャッシュを作成します。キャッシュを定義したら、setCache() メソッドを呼び出します。キャッシュに格納されるオブジェクトは厳しくチェックされないため、その他の情報 (人口の規模など) の情報もキャッシュに格納できます。
// 6 つの首都に対するジオコードの応答の配列を構築します。
var city = [
{
name: "Washington, DC",
Status: {
code: 200,
request: "geocode"
},
Placemark: [
{
address: "Washington, DC, USA",
population: "0.563M",
AddressDetails: {
Country: {
CountryNameCode: "US",
AdministrativeArea: {
AdministrativeAreaName: "DC",
Locality: {
LocalityName: "Washington"
}
}
},
Accuracy: 4
},
Point: {
coordinates: [-77.036667, 38.895000, 0]
}
}
]
},
... // その他の都市に対しても同様です。
];
var map;
var geocoder;
// CapitalCitiesCache は標準の GeocodeCache を拡張したカスタム キャッシュです。
// apply(this) を呼び出して親のクラス コンストラクタを呼び出します。
function CapitalCitiesCache() {
GGeocodeCache.apply(this);
}
// 親クラスのインスタンスを子クラスのプロトタイプとして割り当て、
// 親クラスで定義されたすべてのメソッドを子クラスで直接呼び出せる
// ようにします。
CapitalCitiesCache.prototype = new GGeocodeCache();
// reset メソッドを上書きして、首都に対するジオコード応答の
// 配列からの情報が空のキャッシュに格納されるようにします。
CapitalCitiesCache.prototype.reset = function() {
GGeocodeCache.prototype.reset.call(this);
for (var i in city) {
this.put(city[i].name, city[i]);
}
}
map = new GMap2(document.getElementById("map_canvas"));
map.setCenter(new GLatLng(37.441944, -122.141944), 6);
// UsCitiesCache カスタム キャッシュを使用するようにキャッシュを設定します。
geocoder = new GClientGeocoder();
geocoder.setCache(new CapitalCitiesCache());
ローカル検索
お店やサービスを探せるローカル検索機能を追加する場合は、Google AJAX Search API を使用して、サイトにローカル検索コントロールを埋め込むことができます。このコントロールは GControl オブジェクトのサブクラスで、カスタム コントロール作成の良い例です。
このコントロールをマップ API アプリケーションに追加する前に、Google AJAX Search API URL を追加し、そのサービスのマップ API キーを使用する必要があります。また、以下に示すように、そのコントロール オブジェクトのスタイルシートを読み込む必要もあります。
// コードを読み込みます。
<script src="http://www.google.com/uds/api?file=uds.js&v=1.0&key=ABCDEF"
type="text/javascript"></script>
<script src="http://www.google.com/uds/solutions/localsearch/gmlocalsearch.js"
type="text/javascript"></script>
// スタイルシートを読み込みます。
<style type="text/css">
@import url("http://www.google.com/uds/css/gsearch.css");
@import url("http://www.google.com/uds/solutions/localsearch/gmlocalsearch.css");
</style>
または、AJAX Loader を使用して、共通ローダー経由でこれらのモジュールすべてを読み込むこともできます。
これらの準備作業を行ったら、コントロール自体の読み込みは比較的簡単です。
// 地図を作成します。
var map = new GMap2(document.getElementById("map_canvas"));
// ローカル検索コントロールを作成して地図に追加します。
var lsc = new google.maps.LocalSearch();
map.addControl(new google.maps.LocalSearch());
例を表示 (control-localsearch.html)
ローカル検索コントロールの詳細については、Google AJAX Search API Reference を参照してください。
KML オーバーレイと GeoRSS オーバーレイ
Google マップ API は、地理情報の表示に KML データ形式と GeoRSS データ形式をサポートしています。これらのデータ形式は GGeoXml オブジェクトを使用して地図に追加されます。このオブジェクトのコンストラクタは、パブリックにアクセス可能な XML ファイルの URL を取得します。GGeoXml の目印は GMarker として表示され、GGeoXml のポリラインとポリゴンは Google マップ API のポリラインとポリゴンとして表示されます。KML ファイル内の <GroundOverlay> 要素は、GGroundOverlay 要素として地図上に表示されます。
GGeoXml オブジェクトは、addOverlay() メソッドを使用して地図に追加されます (地図から削除するには、removeOverlay() を使用します)。KML と GeoRSS 両方の XML ファイルがサポートされています。
// GGeoXml コンストラクタは、KML または GeoRSS ファイルを指す URL を取得します。
// GGeoXml オブジェクトはオーバーレイとして地図に追加し、削除するときもオーバーレイとして削除します。
// マップ API により、ファイルが KML ファイルが GeoRSS ファイルかが暗黙的に特定されます。
var map;
var geoXml = new GGeoXml("http://mapgadgets.googlepages.com/cta.kml");
function onLoad() {
if (GBrowserIsCompatible()) {
map = new GMap2(document.getElementById("map_canvas"));
map.addControl(new GLargeMapControl());
map.setCenter(new GLatLng(41.875696,-87.624207), 11);
map.addControl(new GLargeMapControl());
map.addOverlay(geoXml);
}
}
GeoRSS の例を表示 (geoxml-rss.html)
渋滞情報オーバレイ
Google マップ API では、GOverlay インターフェースを実装する GTrafficOverlay オブジェクトを使用して、渋滞情報を地図に追加できます。渋滞情報を地図に追加するには、GMap2.addOverlay() メソッドを使用します。GTrafficOverlay には、渋滞情報オーバレイの表示を切り替えるための 2 つのメソッド (hide() と show()) があります渋滞情報はサポートされている都市に対してのみ表示されます。
// GTrafficOverlayに固有の点は、そのタイプのオブジェクトを 1 つだけ
// 地図に追加する必要があることです。複数の渋滞情報オーバーレイを追加しても、
// 利点が増すわけではありません。
var map;
var trafficInfo = new GTrafficOverlay();
function initialize() {
map = new GMap2(document.getElementById("map_canvas"));
map.setCenter(new GLatLng(49.496675,-102.65625), 3);
map.addOverlay(trafficInfo);
}
渋滞情報オーバレイの例を表示 (trafficOverlay.html)
運転ルート
GDirections オブジェクトを使用して、Google マップ API で運転ルートを追加できます。GDirections オブジェクトは、ルート結果の要求と受信に、クエリ文字列 (「New York, NY to Chicago, IL」など) または指定されたテキストの緯度と経度 (「40.712882, -73.967257 to 41.943181,-87.770677」など) のいずれかを使用します。また、GDirections オブジェクトは一連の地点を使用した、複数の部分からなる運転ルートもサポートしています。ルートは、地図上にルートを描画したポリライン、DIV 要素内の一連のテキストによる説明 (「ウィリアムズバーグ ブリッジ ランプで右折」など)、またはその両方で表示されます。
Google マップ API でルートを使用するには、タイプ GDirections のオブジェクトを作成し、結果の受信と表示に GMap2 オブジェクトまたは DIV、あるいはその両方を指定します。デフォルトでは、返されたルートに応じて地図の中心と範囲が決定されます (ただし、GDirectionOptions オブジェクト内のパラメータを使用して変更できます)。
運転ルートの要求には GDirections.load() メソッドを使用します。このメソッドは、クエリ文字列とオプションの GDirectionsOptions パラメータのセットを取ります。GDirections オブジェクトが、指定された GMap2 オブジェクトで構築された場合、返されるルートにはポリラインのオーバーレイが含まれます。GDirections オブジェクトが、指定された DIV 要素で構築された場合、返されるルートには GStep オブジェクトのセットを含む GRoute オブジェクトが含まれます (複数の地点を含むルートで構成されている場合、返されるルートには複数の GRoute オブジェクトが含まれ、各オブジェクトは一連の GStep オブジェクトで構成されます)。
返された情報は、ルート オブジェクトにすぐには格納されません。そのため、GDirections では "load" イベントが定義されており、このイベントをインターセプトして状態を判断できます。
ルートが返されたら、GDirections オブジェクトは結果を内部的に格納します。この結果は、GDirections.getPolyline() メソッドまたは GDirections.getRoute(i:Number) メソッド、あるいはその両方を使用して取得できます。ルート内のステップは GRoute.getStep(i:Number) メソッド、そのステップの HTML 形式の要約は GStep.getDescriptionHtml() を使用してそれぞれ取得できます。
// ルートのオブジェクトを作成し、計算されたルート結果を保持する
// 地図または DIV を登録します。
var map;
var directionsPanel;
var directions;
function initialize() {
map = new GMap2(document.getElementById("map_canvas"));
directionsPanel = document.getElementById("my_textual_div");
map.setCenter(new GLatLng(49.496675,-102.65625), 3);
directions = new GDirections(map, directionsPanel);
directions.load("New York, NY to Chicago, IL");
}
GDirections オブジェクトは複数の地点を含むルートもサポートしています。複数の地点を含むルートは GDirections.loadFromWaypoints()メソッドを使用して構築できます。このメソッドは、テキストで入力された住所または緯度と経度の点の配列を取得します。各ウェイポイントは個別のルートとして計算され、それぞれ一連の GStep オブジェクトを含む個別の GRoute オブジェクトで返されます。
GRoute オブジェクトは、ルートのステップ数 (タイプ GStep) 、出発地点と到着地点のジオコード、および距離、時間、到着地点の正確な緯度と経度 (ジオコードが道路区分上にない場合は、到着地点のジオコードと異なる場合があります) などの計算されたその他の情報を格納します。各 GStep オブジェクトにも、テキスト (「サンノゼ方面のランプを経由して US-101 (南) に合流」など) の説明に加えて、距離、時間、正確な緯度と経度を含む計算された情報が含まれます。
GDirections オブジェクトは、インターセプト可能な次の 3 つのイベントを発生させます。
- "
load": このイベントは、ルート結果が正常に返されたときに、オーバーレイ要素が地図やパネルに追加される前にトリガされます。 - "
addoverlay": このイベントは、ポリラインまたはテキストのルート コンポーネント、あるいはその両方が、地図または DIV 要素、あるいはその両方に追加された後にトリガされます。 - "
error": このイベントは、ルート要求でエラーが発生した場合にトリガされます。呼び出し元は、GDirections.getStatus()を使用してエラーに関する詳細情報を取得できます。
Directions API パッケージの各種オブジェクト、メソッド、およびイベントの詳細なドキュメントについては、API リファレンスを参照してください。