Google Maps JavaScript API V2 服务
请注意：Google Maps JavaScript API 第 2 版自 2010 年 5 月 19 日起已正式弃用。根据我们的弃用政策，该 V2 API 会继续工作，但我们建议您将自己的代码迁移到 Maps JavaScript API 第 3 版中。
- 服务概述
- XML 和数据解析
- 地址解析
- 地址解析对象
- 提取结构化地址
- 反向地址解析
- 地址解析缓存
- 使用地址解析网络服务
- 使用街道视图全景对象
-
GStreetviewPanorama对象 - 街道视图叠加层
- 在 Street View 中显示用户照片
- 街道视图客户端查询
-
- 与 Google 地球集成
- 载入 Google 地球插件
- 添加 Google 地球地图类型
- 在 Google 地图 API 中访问 Google 地球 API
- 向地图添加本地搜索
- 设置 GoogleBar
- 使用 Google AdSense for Maps 投放广告
- 在
GoogleBar中投放广告 - 使用地图广告单元投放广告
- 在
- KML 和 GeoRSS 叠加层
- 交通叠加层
- 路线
- 载入行车路线
- 出行方式
- 处理返回的行车路线
- 路线和路段
服务概述
Google 地图 API 会定期进行扩展以添加新的功能和特性，通常这些功能和特性会先在 maps.google.com 上发布。本部分包含了上述这些服务。注意：由于“服务”的定义在某种程度上较为模糊，因此本部分所涉及的内容也较为广泛。从根本上说，我们把无法归到其他类别下的精华内容都归到了此部分中。
XML 和数据解析
Google Maps API 可导出一种工厂方法，用于创建独立于浏览器的 XmlHttpRequest() 对象，该对象在 Internet Explorer、Firefox 和 Safari 的较新版本中均可使用。与所有的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 还可导出较为简单的 GDownloadUrl() 方法，适用于避免检查 XmlHttpRequest() readyState 的典型 HTTP GET 请求。可使用 GDownloadUrl() 对上例进行改写，具体如下：
GDownloadUrl("myfile.txt", function(data, responseCode) {alert(data); });
您可以使用静态方法 GXml.parse() 来解析 XML 文档，该方法采用了 XML 字符串作为其唯一参数。该方法兼容大部分热门的浏览器，但如果浏览器不支持 XML 本地解析，则会引发异常。
在此示例中，我们使用 GDownloadUrl 方法下载一个静态文件 ("data.xml")，该文件中包含一个 XML 格式的纬度/经度坐标列表。下载完成后，我们使用 GXml 解析该 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);// Download the data in data.xml and load it on the map. The format we // expect is: //// // // 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 Maps API 包含了“地址解析”网络服务，您可以直接通过 HTTP 请求或使用 GClientGeocoder 对象进行访问。
Google 地图 API 提供客户端地址解析器，用于动态地对用户输入的地址进行解析。相反地，如果您希望对静态的已知地址进行地址解析，请参见地址解析服务文档。
地址解析对象
您可以通过 GClientGeocoder 对象访问 Google Maps API 地址解析服务，还可以使用 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);// As this is user-generated content, we display it as// text rather than HTML to reduce XSS vulnerabilities.marker.openInfoWindow(document.createTextNode(address));}}); }
查看示例 (geocoding-simple.html)
您还可以对 Maps API 地址解析器进行修改，以便通过 GClientGeocoder.setViewport() 方法优先显示指定视口（表现为 GLatLngBounds 类型的边框）内的结果。您可以使用 GClientGeocoder.setBaseCountryCode() 方法返回针对特定域（国家/地区）定制的结果。对于 Google Maps 主应用程序提供地址解析服务的每个区域，您都可以向其发送地址解析请求。例如，如果您使用国家/地区代码“es”将域指定为西班牙 (http://maps.google.es)，那么您在搜索“托莱多”时，系统返回的结果会与通过美国默认域 (http://maps.google.com) 获得的结果不同。
提取结构化地址
如果您希望访问关于某个地址的结构化信息，则可使用 GClientGeocoder 提供的 getLocations() 方法，该方法会返回一个包含以下信息的 JSON 对象：
-
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() 方法对地址进行地址解析，从 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 + '
' + 'Country code: ' + place.AddressDetails.Country.CountryNameCode);} }
查看示例 (geocoding-extraction.html)
反向地址解析
“地址解析”这一术语通常指将易于理解的地址转换成地图上的一个点的过程。与此相反，将地图上的点转换成易于理解的地址的这一过程则称为“反向地址解析”。
GClientGeocoder.getLocations() 方法同时支持标准地址解析和反向地址解析。如果您向此方法传递一个 GLatLng 对象（而不是 String 地址），则地址解析器会执行反向查找，并返回最接近的可寻址位置的结构化 JSON 对象。请注意，如果所提供的 GLatLng 与所有可寻址位置均未能精确匹配，那么，最接近的可寻址位置与查询的原始纬度和经度值之间可能有一段距离。
注意：反向地址解析并不能做到完全精确。地址解析器会试图在一定的偏差范围内查找最接近的可寻址位置；如果找不到匹配项，则地址解析器通常会返回G_GEO_UNKNOWN_ADDRESS (602) 状态代码。
var map; var geocoder; var address;function initialize() {map = new GMap2(document.getElementById("map_canvas"));map.setCenter(new GLatLng(40.730885,-73.997383), 15);map.addControl(new GLargeMapControl);GEvent.addListener(map, "click", getAddress);geocoder = new GClientGeocoder(); }function getAddress(overlay, latlng) {if (latlng != null) {address = latlng;geocoder.getLocations(latlng, showAddress);} }function showAddress(response) {map.clearOverlays();if (!response || response.Status.code != 200) {alert("Status Code:" + response.Status.code);} 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('orig latlng:' + response.name + '
' + 'latlng:' + place.Point.coordinates[1] + "," + place.Point.coordinates[0] + '
' +'Status Code:' + response.Status.code + '
' +'Status Request:' + response.Status.request + '
' +'Address:' + place.address + '
' +'Accuracy:' + place.AddressDetails.Accuracy + '
' +'Country code: ' + place.AddressDetails.Country.CountryNameCode);} }
查看示例 (geocoding-reverse.html)
地址解析缓存
默认情况下，GClientGeocoder 会配备客户端缓存。该缓存用于存储地址解析器响应，这样，当对某个地址重复进行地址解析时，地址解析器就能更快地作出响应。要关闭缓存，您只需向 GClientGeocoder 对象的 setCache() 方法传递 null 即可。不过，我们建议您启用缓存功能，因为这样可以提高性能。要更改 GClientGeocoder 正在使用的缓存，请调用 setCache()，然后传入新的缓存。要清空当前缓存中的内容，请直接在地址解析器或缓存上调用 reset() 方法。
我们鼓励开发人员构建自己的客户端缓存。在此示例中，我们构建了一个缓存，其中包含了对六座首都（属于 geocoding API 涵盖的国家/地区）的预先计算的地址解析器响应。我们先构建了地址解析响应的数组，然后，创建了用于扩展标准 GeocodeCache 的自定义缓存。定义缓存后调用 setCache() 方法。系统对缓存中存储的对象不会执行严格的检查，因此您也可以在其中存储其他信息（比如人口规模）。
// Builds an array of geocode responses for the 6 capitals 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]}}]},... // etc., and so on for other cities ];var map;var geocoder;// CapitalCitiesCache is a custom cache that extends the standard GeocodeCache.// We call apply(this) to invoke the parent's class constructor.function CapitalCitiesCache() {GGeocodeCache.apply(this);}// Assigns an instance of the parent class as a prototype of the// child class, to make sure that all methods defined on the parent// class can be directly invoked on the child class.CapitalCitiesCache.prototype = new GGeocodeCache();// Override the reset method to populate the empty cache with// information from our array of geocode responses for capitals.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);// Here we set the cache to use the UsCitiesCache custom cache.geocoder = new GClientGeocoder();geocoder.setCache(new CapitalCitiesCache());
查看示例 (geocoding-cache.html)
使用地址解析网络服务
Google 也提供直接通过 HTTP 执行的地址解析网络服务。这种地址解析服务与 JavaScript Google Maps API 不同。对于动态的地址解析请求或实时的检索地址解析请求，我们不建议使用地址解析网络服务；您可以改为使用本章中介绍的 JavaScript 客户端地址解析器。但是，如果您要填充静态数据组、需要进行调试或 JavaScript GClientGeocoder 对象不可用，则建议使用 HTTP 地址解析器。
有关详情，请参见地址解析网络服务。
使用 Street View 对象
使用 Street View 全景图对象要求客户端浏览器支持 Flash 插件。
Google Street View 提供了从指定道路遍及 Google Maps 覆盖范围的 360 度全景视图。Street View 示例图片如下所示。
Google 街道视图使用 Flash® 插件来显示这些交互图像，大部分浏览器都支持该插件。Google Maps API 提供了 Street View 服务，用于获取和处理 Google Maps Street View 中使用的图像。
新功能！Street View 服务现可提供来自支持的图片存储区（如 Panaramio 和 Picasa）的用户照片。请参见下方的在 Street View 中显示用户照片。
GStreetviewPanorama 对象
通过使用 GStreetviewPanorama 对象可支持街道视图图像，该对象提供街道视图 Flash® 查看器的 API 接口。要将街道视图合并到地图 API 的应用程序中，您需要遵循以下较为简单的步骤：
- 创建一个容器（通常是
元素），用于存放街道视图 Flash® 查看器。 - 创建
GStreetviewPanorama对象，并将其放置在容器内。 - 初始化 Street View 对象，以便引用特定的位置，并显示初始的“视点”(POV)。
- 通过检查
603错误值来处理不支持的浏览器。
GStreetviewPanorama 对象要求其构造函数内包含一个容器元素，它还可让您使用 GStreetviewPanoramaOptions 参数设置其地址（可选）。您可以在构建后在该对象上调用 setLocationAndPOV()，以更改其位置和 POV。
注意：尽管街道视图功能专门用来与地图结合使用，但这并非强制性要求。您也可以在不使用地图的情况下单独使用街道视图对象。
有关容器和设置位置及视点的详细信息，将在下文中介绍。
Street View 容器
Street View Flash 查看器需要一个容器 DOM 节点，以便在其中显示其内容（通常为 元素）。为了实现全景图像的最佳显示结果，我们建议其最低尺寸应为 200x200 像素。我们同样不建议使用大型查看器，因为这样可能导致 Flash 查看器消耗过多内存，从而对浏览器的性能产生负面影响。
GStreetviewPanorama 构造函数需要一个 container 参数，用于识别在其中显示 Street View Flash 查看器的初始容器元素。您可以 hide() GStreetviewPanorama 对象，以暂时将其隐藏起来；也可以 show() 该对象，以重新显示查看器。
如果您希望更改 Street View Flash 查看器的容器，可随时向其发送 setContainer() 方法，并传递它应当附加到的新元素。如果该容器的大小经过了重新调整，那么您可以向GStreetviewPanorama 对象发送 checkResize() 方法，可强制重新调整该对象的大小，以使其适应新的尺寸。
如果您希望从 DOM 中彻底删除 Street View Flash 查看器并释放其内存，请向该对象传递 remove() 方法。从 DOM 中删除街道视图对象的容器元素之前，请务必调用该方法，否则将导致内存泄漏和/或客户端浏览器上发生 Javascript 错误。
街道视图位置
Street View 图片由位置（对应于 GLatLng）和特定方向 (GPov) 组成，这两项共同标识了图片显示的视图。您可以在构建 Street View 对象时，使用可选的GStreetviewPanoramaOptions 参数来指定这两项参数。
要了解 Street View 当前支持的城市列表，请查看 Google Maps 帮助中心。要确定某个地点是否支持 Street View 数据，有三种基本方法：
- 对于已知有效的 Street View 位置，您可以存储其
GLatLng。 - 您可以检查
GStreetviewOverlay的图块叠加层并直接检查道路网络。支持 Street View 的道路会在叠加层上以蓝色突出显示。然后，您就可以使用点击事件或地址解析逻辑向GStreetviewPanorama对象传递支持的地点了（请参见街道视图叠加层。） - 您可以使用
GStreetviewClient对象，对指定了传递GLatLng的街道视图对象执行查询。GStreetviewClient对象支持使用大量查询来查找全景数据。（请参见Street View 客户查询）。
请注意，最后两种方法并不精确：在这些情况下，Street View 服务不要求提供（一般也不接收）精确的纬度和经度，而是搜索指定的 GLatLng“附近”是否存在全景图数据。
以下示例使用了 GStreetviewPanoramaOptions 来指定 Street View 所使用的初始纬度和经度。POV 项已留空，表明默认视图朝向北方。
var fenwayPark = new GLatLng(42.345573,-71.098326); panoramaOptions = { latlng:fenwayPark }; var myPano = new GStreetviewPanorama(document.getElementById("pano"), panoramaOptions);
查看示例 (streetview-simple.html)
街道视图错误处理
由于街道视图要求支持 Flash® 插件，因此，您需要编写代码来测试用户浏览器是否支持该插件。您也可以通过注册一个对 GStreetviewPanorama 对象上的 error 事件进行侦听的事件侦听器，在您的应用程序中进行这项检查。error 事件将会传递一个错误代码，您可以根据其进行判断。
下面的示例代码针对是否支持 Flash 插件执行快速检查，如果不支持 Flash 则显示一个警告对话框。
var fenwayPark = new GLatLng(42.345573,-71.098326); panoramaOptions = { latlng:fenwayPark }; myPano = new GStreetviewPanorama(document.getElementById("pano"), panoramaOptions); GEvent.addListener(myPano, "error", handleNoFlash);function handleNoFlash(errorCode) {if (errorCode == 603) {alert("Error: Flash doesn't appear to be supported by your browser");return;} }
Street View 视点 (POV)
Street View 位置定义了图片的镜头固定位置，但未定义该图片的镜头方向。为此，GPov 对象常量会定义三个属性：
-
yaw定义了镜头位置周围相对于正北的旋转角度（以度为单位）。偏航角按顺时针方向测量（90 度为正东）。 -
pitch定义了相对于镜头初始默认倾斜度的“向上”或“向下”的角度差异，倾斜度通常（但并不总是）水平的。（例如，从山上拍摄的图像展示的默认跨度就可能不是水平的。）仰视时测得的跨度角为负值（与默认跨度成 -90 度垂直向上正交）；俯视时测得的跨度角为正值（与默认跨度成 +90 度垂直向下正交）。 -
zoom定义了该视图的缩放级别（有效地限制了“视野”），0 代表最低缩放级别。Street View 的位置不同，所提供的缩放级别高低也有所不同。
默认情况下，这些值均为 0，即定义了一个朝向北方且视野最宽阔的水平视图。
设置全景视图
如前所述，您可以在构建全景图对象时，使用 GStreetviewPanoramaOptions 参数同时设置其位置和 GPov；
fenwayPark = new GLatLng(42.345573,-71.098326); myPOV = {yaw:370.64659986187695,pitch:-20}; svOpts = {latlng:fenwayPark, pov:myPOV}; var myPano = new GStreetviewPanorama(document.getElementById("pano"), svOpts);也可以在
GStreetviewPanorama 对象构建完毕后，使用
setLocationAndPOV() 方法同时设置位置和 POV。在以下示例中，我们会创建
GStreetviewPanorama 对象，然后将其位置和 POV 设置为特定值。
var myPano = new GStreetviewPanorama(document.getElementById("pano")); fenwayPark = new GLatLng(42.345573,-71.098326); myPOV = {yaw:370.64659986187695,pitch:-20}; myPano.setLocationAndPOV(fenwayPark, myPOV);
查看示例 (streetview-object.html)
使用街道视图叠加层
要确定某条道路是否支持 Street View，最简单的办法是通过 GStreetviewOverlay 对象。只需创建该类型的叠加层，然后将其添加到地图即可；包含 Street View 数据的道路会在地图上以蓝色轮廓突出显示出来。
var map = new GMap2(document.getElementById("map_canvas")); map.setCenter(new GLatLng(37.4419, -122.1419), 13); svOverlay = new GStreetviewOverlay(); map.addOverlay(svOverlay);
查看示例 (streetview-layer.html)
当您知道某个地理区域支持街道视图后，可以通过填充 GStreetviewPanorama 对象在有效的街道视图道路上添加可响应单击操作的逻辑。
var myPano = new GStreetviewPanorama(document.getElementById("pano")); var map = new GMap2(document.getElementById("map_canvas")); map.setCenter(new GLatLng(42.345573,-71.098326), 14); svOverlay = new GStreetviewOverlay(); map.addOverlay(svOverlay); GEvent.addListener(map,"click", function(overlay,latlng) {myPano.setLocationAndPOV(latlng); });
查看示例 (streetview-click.html)
如果您知道某个特定位置支持街道视图，则可以保存该位置信息和 POV 并将这些信息放入对象本身。
在 Street View 中显示用户照片
GStreetviewPanorama 对象不仅支持 Street View 图像，还可显示来自热门的照片存储区（如 Picasa 和 Panaramio）的用户照片。下方显示了包含用户照片的 Street View 示例：
当导航到包含附近用户照片的位置时，Street View 会显示一个标有“用户照片”的小窗口，点击该窗口会显示一组用户照片。
启用用户照片
默认情况下，Street View 内的用户照片处于启用状态。要停用 Street View 内的用户照片功能，请将 GStreetviewPanoramaOptions 的 features 参数内的 userPhotos 设置为 false。此外，您可在该选项的 userPhotoOptions 字段中指定您要启用的特定照片存储区。
目前，我们支持以下 GStreetviewUserPhotoOptions：
-
"panoramio" -
"picasa" -
"flickr"
如果您不指定自己感兴趣的特定存储区，则系统会启用所有的照片存储区。
以下示例显示了波士顿的地图，其中同时启用了 Picasa 和 Panoramio 的用户照片：
var panoOpts = {features: {streetView: true,userPhotos: true},userPhotoOptions: {photoRepositories: [ 'panoramio', 'picasa']} }; var myPano = new GStreetviewPanorama(document.getElementById("pano"), panoOpts); var boston = new GLatLng(42.345573,-71.098326); GEvent.addListener(myPano, "error", handleNoFlash); var map = new GMap2(document.getElementById("map_canvas")); map.setCenter(boston, 14); svOverlay = new GStreetviewOverlay(); map.addOverlay(svOverlay); myPano.setLocationAndPOV(boston);
查看示例 (streetview-photos.html)
注意：在本示例中，我们本无需明确启用用户照片，但此处启用的目的在于演示该 API。
检索特定照片
某些照片存储区（当前仅 "panoramio" 存储区）可让您标识特定照片。Street View 对象可让您选择特定照片并将其显示在 Street View 对象中，方法是使用 GPhotoSpec 对象来选择照片。GPhotoSpec 由一个 repository 标识符，以及一个用于标识单张照片的 id 字段组成。
以下示例展示了波士顿芬威球场的一张照片，这是 2004 年世界大赛冠军队伍“红袜队”的主场：
var panoOpts = {features: {streetView: false,userPhotos: true},userPhotoOptions: {photoRepositories: [ 'panoramio']} }; var myPano = new GStreetviewPanorama(document.getElementById("pano"), panoOpts); var fenway = {repository: "panoramio",id: 8323025 }; GEvent.addListener(myPano, "error", handleNoFlash); myPano.setUserPhoto(fenway);
查看示例 (streetview-photo-id.html)
有关获取单张图片 ID 的详情，请查看 Panoramio API。
街道视图客户端查询
从用户的角度而言，通过直接检查 GStreetviewOverlay 来确定道路是否支持 Street View 的方式通常不可行，或者不理想。因此，API 提供了通过编程的方式请求并检索 Street View 数据的服务。使用 GStreetviewClient 对象可使该服务更加便捷。
执行街道视图查找
GStreetviewClient 对象会使用 Google 的 Street View 服务来查找全景图数据。由于该查找操作是异步进行的，因此，此类的方法需要回调函数，以便在收到数据时执行。所有指定的回调在没有返回值时会传递 null，因此，您应当在自己的回调函数内检查是否存在这种情况。
GStreetviewClient 方法 getNearestPanoramaLatLng() 会通过指定的位置检索附近全景图像的 GLatLng（其自身作为 GLatLng 进行传递）。
getNearestPanorama() 和 getPanoramaById() 都会改为检索 GStreetviewData 对象，它们会存储关于特定全景图对象的元数据。以下部分对这些数据进行了说明。
处理客户端响应
GStreetviewData 对象的结构由三个属性构成：location、copyright（包含当前显示的特定图片的相关信息）和 links（提供相邻全景图对象的相关信息）。以下说明了这些属性的结构：
# The location property uses the GStreetviewLocation object literal
location: {latlng: GLatLng, pov: { yaw: String, pitch: String, zoom: String}, description: String, panoId: String
}copyright: String# The links property uses the GStreetviewLink object literal
links[]: {yaw: String, description: String, panoId: String
}
（有关 GStreetviewLocation 和 GStreetviewLink 对象常量的详细说明，请查看Google 地图 API 参考。）
注意：请勿将 GStreetviewData.location 属性与 window.location 属性混淆。如果您尝试从该对象的 location 属性中提取数据，则请确保您实际收到了从 Street View 服务器返回的响应（请参见下方）；否则 location 属性会默认为 window.location，且会发生未知行为。
如果对 GStreetviewClient 对象的请求成功，则会向指定的回调函数传递 GLatLng 或 GStreetviewData 对象。检索 Street View 数据是异步进行的，但客户对象可能不会检索这些数据对象，因此您的代码不应依赖这些对象。您应当始终检查所有请求返回的 code 值（正常情况下一定会返回）。以下代码段说明了此概念。
panoClient = new GStreetviewClient(); panoClient.getPanoramaById(panoData.location.panoId, processReturnedData);function processReturnedData(panoData) {if (panoData.code != 200) {GLog.write('showPanoData: Server rejected with code: ' + panoData.code);return;}// Code to actually process the GStreetviewData object is contained here}
下方显示了包含示例 GStreetviewData 结构的完整响应：
{location: {latlng: GLatLng("42.345566, -71.098354")pov: {yaw: "370.64659986187695"pitch: "-20"zoom: "1"}description: "Yawkey Way"panoId: "-KNGDaZvSQjMqug7ISM_CA"}copyright: "© 2008 Google"links:[ {yaw: "0"description: "Yawkey Way"panoId: "S142iWXa_4Fi7L7d8HKhuQ"},{yaw: "0"description: "Yawkey Way"panoId: "2vFI79AjOpHTAYJSCKquFg"}] }
下方的示例应用程序显示了初始的全景图对象并提取了其 ID，然后在返回的 GStreetviewData 对象中存储了关联的 Panorama 对象，最后显示了与该 Street View 对象相关联的数据组。每当用户点击“下一个”时，该流程就会重复执行，从而让用户“走过”一系列邻近的全景图对象。
var map; var myPano; var panoClient; var nextPanoId;function initialize() {var fenwayPark = new GLatLng(42.345573,-71.098326);var fenwayPOV = {yaw:370.64659986187695,pitch:-20};panoClient = new GStreetviewClient(); map = new GMap2(document.getElementById("map_canvas"));map.setCenter(fenwayPark, 15);GEvent.addListener(map, "click", function(overlay,latlng) {panoClient.getNearestPanorama(latlng, showPanoData);});myPano = new GStreetviewPanorama(document.getElementById("pano"));myPano.setLocationAndPOV(fenwayPark, fenwayPOV);GEvent.addListener(myPano, "error", handleNoFlash); panoClient.getNearestPanorama(fenwayPark, showPanoData); }function showPanoData(panoData) {if (panoData.code != 200) {GLog.write('showPanoData: Server rejected with code: ' + panoData.code);return;}nextPanoId = panoData.links[0].panoId;var displayString = ["Panorama ID: " + panoData.location.panoId,"LatLng: " + panoData.location.latlng,"Copyright: " + panoData.copyright,"Description: " + panoData.location.description,"Next Pano ID: " + panoData.links[0].panoId].join("
");map.openInfoWindowHtml(panoData.location.latlng, displayString);GLog.write('Viewer moved to' + panoData.location.latlng);myPano.setLocationAndPOV(panoData.location.latlng); }function next() {// Get the next panoId// Note that this is not sophisticated. At the end of the block, it will get stuckpanoClient.getPanoramaById(nextPanoId, showPanoData); }function handleNoFlash(errorCode) {if (errorCode == 603) {alert("Error: Flash doesn't appear to be supported by your browser");return;} }
查看示例 (streetview-data.html)
与 Google 地球插件集成
使用 Google 地图 API，开发人员可对 Google 地图 API 的应用程序中的 Google 地球插件实例进行操作。Google 地球的地图层通过外观和行为都像独立 Google 地球应用程序的单独GMapType 载入，这样您就可以在浏览器中旋转视角、观看立体图以及查看 Google 地球 KML 信息。
注意：用户的计算机上只有安装了 Google 地球插件之后，才能使用 Google 地球 GMapType。目前，该插件可以在 Microsoft Windows 和 Apple Mac OS X 中使用。有关完整的系统要求说明，请参见 Google 地球 API 开发人员指南。
Google 地球插件也可以通过其自身的 API 进行控制，该 API 与 Google 地图 API 是互相独立的，并且各不相同。有关如何使用该插件和 Google 地球 API 的详细信息，请参见Google 地球 API 开发人员指南。
载入 Google 地球插件
要安装该插件，请访问 Google 地球 API 安装说明，或浏览任意一个使用 Google 地球插件的网站。在您的应用程序中，尚未安装该插件的最终用户会在切换到 Google 地球GMapType 时看到下载链接。安装成功后，Google 地球插件会自动载入（在某些浏览器中，该插件会在重新载入网页时载入）。
添加 Google 地球地图类型
要将 Google 地球实例添加到您的地图，只需通过 GMap2.addMapType() 将 G_SATELLITE_3D_MAP 添加到您的地图即可。然后，可以通过 GMap2.setMapType() 直接显示这一地图类型，也可以让用户自己在 GMapTypeControl 中选择这一地图类型，方法是使用 GMap2.addControl() 添加一个地图类型控件。
以下代码会添加 G_SATELLITE_3D_MAP 地图类型，然后在地图容器中显式载入 Google 地球。
var map = new GMap2(document.getElementById("map_canvas"),{ size: new GSize(640,480) } ); map.setCenter(new GLatLng(42.366662,-71.106262), 11);// Enable the Earth map type map.addMapType(G_SATELLITE_3D_MAP);var mapControl = new GMapTypeControl(); map.addControl(mapControl); map.setMapType(G_SATELLITE_3D_MAP);
查看示例 (services-earth-plugin.html)
在 Google 地图 API 中访问 Google 地球 API
也可以在 Google 地图 API 中访问 Google 地球 API 对象。要访问三维地图类型的 GEPlugin 根对象，请调用 GMap2.getEarthInstance：
map.getEarthInstance(function(ge) {// Direct Earth API calls can go herege.getLayerRoot().enableLayerById(ge.LAYER_BORDERS, true); // Turn on borders and labels });
向地图添加本地搜索
为了让您的用户可以搜索本地商户，您可以使用 GoogleBar 将本地搜索控件嵌入自己的网站。GoogleBar 进行了更新，采用全新的用户界面，并且还添加了广告结果，您可以配置这些广告结果使您的 API 网站获得收益。
设置 GoogleBar
要使用 GoogleBar，您必须先使用传递给 GMap2 构造函数的 GGoogleBarOptions 对象指定 GoogleBar 的行为。地图构建完成后，可通过调用 GMap2.enableGoogleBar() 启用 GoogleBar。GoogleBar 已进行更新，具有全新的外观，并能够向地图 API 的网站添加广告收益流。
注意：GoogleBar 提供了一款针对 Google AJAX 搜索 API 的小巧封装器，这是一个独立产品，拥有自己的使用条款。
经过重新设计的 GoogleBar 在行为上与之前的版本不同，因此，我们以“可选”设置的形式提供新的用户界面。要启用新的 GoogleBar，请在 GGoogleBarOptions 对象中将 style属性设置为“new”。在不久的将来，我们会将此行为设置为默认行为。
下面的示例设置了具有新外观的 GoogleBar：
var map; if (GBrowserIsCompatible()) {var mapOptions = {googleBarOptions : {style : "new",}}map = new GMap2(document.getElementById("map_canvas"), mapOptions);map.setCenter(new GLatLng(33.956461,-118.396225), 13);map.setUIToDefault();map.enableGoogleBar(); }
查看示例 (control-googlebar.html)
请注意，通过该控件获取的结果中会包含广告。如果要从 GoogleBar 的广告搜索结果中获取收益，请参见下面的获取广告收益。
使用 AdSense for Maps 投放广告
Google 现在提供数种 AdSense for Maps 产品，使您的 Google 地图 API 应用程序可以赚取收益：
- 使用
GoogleBar在本地商户搜索结果旁显示广告 - 使用地图广告单元，根据地图视口显示广告
要通过这种广告获取收益，您可以分别将这些 AdSense for Maps 对象链接到 AdSense 帐户，该帐户必须已启用 AdSense for Search 或 AdSense for Content。
这些广告方法存在根本区别，因而需要使用不同的 Google AdSense 产品。要根据用户直接进行的搜索在 GoogleBar 中显示广告，需要启用您的 AdSense 帐户，这样才能使用 AdSense for Search。要根据查看者视口在地图上的面板中显示广告，需要启用您的 AdSense 帐户，这样才能使用 AdSense for Content。
如果您还没有 AdSense 帐户，请注册帐户。注册帐户之后（或者如果您已经拥有帐户），请确保您的帐户已启用 AdSense for Search 和/或 AdSense for Content。
拥有 Adsense for Search 或 AdSense for Content 帐户之后，您将收到 AdSense for Search (AFS) 或 AdSense for Content (AFC) 发布商 ID。您可以在代码中使用该发布商 ID，将显示的任意广告链接到您的 AdSense 帐户。
在 GoogleBar 中投放广告
要使用 GoogleBar 从用户搜索获取广告收益，请在构建地图时，在 GGoogleBarAdsOptions 对象的 client 属性中指定发布商 ID。这样，只要用户点击了您 API 应用程序中的本地结果，您便可以从这次点击中获取广告收益。如果设置了 AdSense for Search channel，则您还可以选择指定该属性。（有关广告渠道的详细信息，请参见此处。）
此外，您还可以指定要与广告关联的 adsafe（广告安全级别），以及显示结果时要使用的 language。
下面的示例显示可获取广告收益的 GoogleBar 设置。请注意，在您的应用程序中，您应当使用自己的发布商 ID。
var map; if (GBrowserIsCompatible()) {var mapOptions = {googleBarOptions : {style : "new",adsOptions: {client: "partner-google-maps-api",channel: "AdSense for Search channel",adsafe: "high",language: "en"}}}map = new GMap2(document.getElementById("map_canvas"), mapOptions);map.setCenter(new GLatLng(33.956461,-118.396225), 13);map.setUIToDefault();map.enableGoogleBar(); }
查看示例 (control-googlebar-ads.html)
有关详细信息，请参见 GGoogleBarAdsOptions API 参考。
使用地图广告单元投放广告
地图广告单元是 AdSense for Maps 组合中的一个新广告选项，在 GAdsManager 构造函数中指定某个选项即可创建该单元。地图广告单元显示一个小面板，其中包含了根据地图查看内容而定制的广告。
在 GAdsManagerOptions 对象中指定 'adunit' 样式可启用地图广告单元。同时请确保在 GAdsManager 构造函数中指定了发布商 ID。这样，只要用户点击了地图广告单元中的广告，且它在您的 API 应用程序中，您便可以从这次点击中获取广告收益。如果设置了 AdSense for Content channel，则您还可以选择指定该属性。（有关广告渠道的详细信息，请参见此处。）
下面的示例显示可获取广告收益的 GAdsManager 设置。请注意，在您的应用程序中，您应当使用自己的发布商 ID。
var publisher_id = yourPublisherID;var adsManagerOptions = {maxAdsOnMap : 2,style: G_ADSMANAGER_STYLE_ADUNIT,// The channel field is optional - replace this field with a channel number // for Google AdSense trackingchannel: 'your_channel_id' };adsManager = new GAdsManager(map, publisher_id, adsManagerOptions); adsManager.enable();
查看示例 (adsmanager-adunit.html)
请注意：在构建广告时，您必须在 GAdManagerOptions 对象内选择该广告的样式。目前仅支持 G_ADSMANAGER_STYLE_ADUNIT 样式。
有关详细信息，请参见 GAdsManager API 参考。
KML/GeoRSS 叠加层
Google Maps API 支持采用 KML 和 GeoRSS 数据格式来显示地理信息。使用 GGeoXml 对象将这些数据格式添加到地图，该对象的构造函数采用可公开访问的 XML 文件的网址作为参数。GGeoXml 地标呈现为 GMarker，而 GGeoXml 折线和多边形呈现为 Google 地图 API 折线和多边形。KML 文件中的 GGroundOverlay 元素。
您可使用 addOverlay() 方法将 GGeoXml 对象添加到地图中（还可以使用 removeOverlay() 将其从地图上删除）。系统同时支持 KML 和 GeoRSS XML 文件。请注意：GGeoXml 是 Google Maps API 内的模块化对象，只有在初次使用后才会完全加载。因此，请仅在页面完全加载后再调用其构造函数。要实现此目的，通常您可以在 的onload 处理程序内调用 GGeoXml 构造函数。
// The GGeoXml constructor takes a URL pointing to a KML or GeoRSS file. // You add the GGeoXml object to the map as an overlay, and remove it as an overlay as well. // The Maps API determines implicitly whether the file is a KML or GeoRSS file.var map; var geoXml;function initialize() {if (GBrowserIsCompatible()) {map = new GMap2(document.getElementById("map_canvas")); geoXml = new GGeoXml("http://gmaps-samples.googlecode.com/svn/trunk/ggeoxml/cta.kml");map.addControl(new GLargeMapControl());map.setCenter(new GLatLng(41.875696,-87.624207), 11); map.addControl(new GLargeMapControl());map.addOverlay(geoXml);} }
查看 GeoRSS 示例 (geoxml-rss.html)
查看 KML 示例 (geoxml-kml.html)
交通叠加层
在 Google Maps API 中，您可以 GTrafficOverlay 对象向自己的地图添加路况信息，该对象用于实现 GOverlay 接口。您可以使用 GMap2.addOverlay() 方法向自己的地图添加路况信息。GTrafficOverlay 拥有两种方法（hide() 和 show()）用于切换路况叠加层的显示方式。路况信息仅对支持的城市显示。
您可以选择使用 GTrafficOverlayOptions 对象常量向 GTrafficOverlay 构造函数传递选项。
// The GTrafficOverlay is unique in that only one object of that type // should be added to a map. Adding multiple traffic overlays produces // no added benefit.var map; var trafficInfo;function initialize() {map = new GMap2(document.getElementById("map_canvas")); map.setCenter(new GLatLng(49.496675,-102.65625), 3); var trafficOptions = {incidents:true};trafficInfo = new GTrafficOverlay(trafficOptions);map.addOverlay(trafficInfo); }
查看交通示例 (trafficOverlay.html)
路线
您可以使用 GDirections 对象来添加计算路线（使用各种交通方式）的功能。GDirections 对象会使用查询字符串（如“纽约州纽约 to 伊利诺伊州芝加哥”）或提供的文本纬度/经度（如“40.712882, -73.967257 to 41.943181,-87.770677”）来请求并接收路线结果。GDirections 对象还支持使用一系列路标的多段路线。路线可以显示为在地图上绘制路线的折线和/或 元素中的一系列文本说明（如“右转上中山南路”）。
要在 Google Maps API 中使用路线，请创建 GDirections 类型的对象，然后指定 GMap2 对象和/或 以接收并显示结果。默认情况下，该地图是按照返回的路线来确定中心和边界的，不过您也可以使用 GDirectionOptions 对象中的参数进行更改。
行车路线
系统会使用 GDirections.load() 方法请求路线。此方法采用了查询字符串和一组可选的 GDirectionsOptions 参数。可用的选项包括：
-
locale指定返回结果时所使用的语言。如果提供该参数，则将覆盖 地图 APIhl参数（如果提供）。如果locale和hl参数均未指定，则系统会使用浏览器的默认语言。 -
travelMode用于指定在计算结果时要使用的交通方式。 -
avoidHighways用于指定在计算路线时应避开高速公路。 -
getPolyline用于指定路线对象应当返回折线数据，以便绘制返回的路线。默认情况下，如果有可显示路线的地图对象，则GDirections对象仅会返回折线数据。如果您将此值设为true而不提供地图，则应当直接处理折线数据。 -
getSteps用于指定应返回文本路线的路线对象（即使在未提供用于显示路线的面板的情况下）。如果您将此值设为true而不提供面板，则应当直接处理路段数据。 -
preserveViewport用于指定地图不应按照返回路线的边框来自动确定中心和缩放级别，而仍应按照当前视口来确定中心。
出行方式
默认情况下，系统会将路线假定为行车路线，但您也可以请求其他出行方式，只需在调用 Directions.load() 方法时传递 GTravelMode 即可。支持以下出行方式：
-
G_TRAVEL_MODE_DRIVING指示使用路网的标准行车路线 -
G_TRAVEL_MODE_WALKING用于请求经过步行街和人行道（如果有的话）的步行路线。
注意：步行路线有时可能不包含畅通的行人通道，因此仅当您在 GDirections 构造函数中提供了 时，系统才支持步行路线；该 用于在返回的带拐弯提示的文本路线中显示警告。如果您未提供 ，则步行路线请求会返回错误。
处理返回的路线
如果 GDirections 对象是使用所提供的 GMap2 对象构建的，则返回的路线将会包含折线叠加层。如果 GDirections 对象是使用所提供的 元素构建的，则返回的路线将会包含 GRoute 对象，其中含有一组 GStep 对象（如果该路线由多点路线构成，则返回的路线将包含多个 GRoute 对象，每个对象均由一组 GStep 对象构成）。
请注意，系统不会立即使用返回的信息填充路线对象。为此，GDirections 对象定义了“load”事件，您可以拦截该事件以确定此状态。
默认情况下，当路线返回后，地图将会显示一条代表路线的折线，而针对该路线提供的文本路线则会显示在 中。GDirections 对象还会在内部存储结果，您可以使用GDirections.getPolyline() 和/或 GDirections.getRoute(i:Number) 方法进行检索。要检索路线内的路段和该路段的 HTML 摘要，您可以分别使用GRoute.getStep(i:Number) 方法和 GStep.getDescriptionHtml() 方法。（请参见下面的路线和路段。）
GDirections 对象还会触发三个事件，您可对其进行拦截：
- “
load”：当系统成功返回路线结果后，且在向地图/面板添加任何叠加层元素之前会触发此事件。 - “
addoverlay”：当系统将折线和/或文本路线组件添加到地图和/或 DIV 元素后会触发此事件。 - “
error”：路线请求导致出错时会触发此事件。调用程序可以使用GDirections.getStatus()以获取关于该错误的更多信息。
// Create a directions object and register a map and DIV to hold the // resulting computed directionsvar 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("from: 500 Memorial Drive, Cambridge, MA to: 4 Yawkey Way, Boston, MA 02215 (Fenway Park)"); }
查看示例 (directions-simple.html)
以下示例与第一个示例相同，只是行车路线通过传递 G_TRAVEL_MODE_WALKING 调用：
查看示例 (directions-walking.html)
路线和路段
GDirections 对象还支持多点路线，您可使用 GDirections.loadFromWaypoints() 方法进行构建。该方法采用了文本输入地址的数组或文本纬度/经度点。每个单独的路标均作为一条单独的路线进行计算，并在独立的 GRoute 对象中返回，其中每个对象均包含一系列 GStep 对象。
GRoute 对象会存储该路线的路段（类型为 GStep）数目、该路线的起点和终点地址解析和计算出的其他信息，如距离、持续时间和端点的精确纬度/经度（如果地址解析不取决于路段，则该纬度/经度可能与终点地址解析有所不同）。每个 GStep 对象还包括对该文本的描述（例如“经过通往南京的斜道驶入 312 国道”）和计算出的信息，包括距离、持续时间和精确的纬度/经度。
有关行车路线 API 包中的各个对象、方法和事件的完整文档，请参阅 API 参考。
查看示例 (directions-advanced.html)
本文来自互联网用户投稿，文章观点仅代表作者本人，不代表本站立场，不承担相关法律责任。如若转载，请注明出处。 如若内容造成侵权/违法违规/事实不符，请点击【内容举报】进行投诉反馈！