展开结构化地址信息

如果您想访问地址的结构化信息，GClientGeocoder提供getLocations方法返回一个JSON对象包含下列的信息。译注：JSON(JavaScript. Object Notation)，是一种轻量级的数据交换格式，

Status

request -- 请求类型，在这里永远是geocode。

code -- 一个回应代码(近似于HTTP状态代码)指示地理译码是否成功。参看状态代码全列表。

Placemark -- 如果地理译码器找到多个结果，那么会返回多个地点。

address -- 一个格式良好的地址。

AddressDetails -- 格式化为xAL(可扩充地址语言)格式的地址。xAL是地址信息格式化方面的国际标准。

  Accuracy -- 这个属性用来说明对给定地址地理译码的结果的精确度。参看精确度的取值范围。

Point -- 在三维空间的点。

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);

  }

}

显示范例 (geocoder2.html)

缓存地理译码

GClientGeocoder类默认情况下装备了一个客户端的缓存。这个缓存会保存地理译码回应，这样当相同的地址被查询的时候，回应会直接从客户端的缓存中返回而不用连接到Google的地理译码器。想关闭缓存机制，可以用参数null调用GClientGeocoder类的setCache方法。然而，我们推荐您保留缓存机制,因为这可以提高性能。要改变使用的缓存，可以用新缓存作为参数调用setCache方法。要清空当前的缓存，可以调用reset方法。

我们鼓励开发者创建它们自己的客户端缓存。在这个例子里，我们用计算好的六个国家的首都的信息构建了一个缓存。首先，我们创建地理译码回应的数组。然后我们创建一个定制的缓存。缓存定义好后，我们用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"));

  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());

显示范例 (geocodercache.html)

HTTP请求方式

想直接让服务器端脚本访问地理译码器，可以发请求到http://maps.google.com/maps/geo?，把如下参数加在地址里面：

·      q -- 你想地理译码的地址。

·      key -- 你的API key。

·      output -- 输出格式。选项是xml，kml，csv或者json。

在这个例子里，我们请求google总部的地理坐标。

http://maps.google.com/maps/geo?q=1600+Amphitheatre+Parkway,+Mountain+View,+CA&output=xml&key=abcdefg

如果你指定输出格式为json，那么回应就是格式化好的JSON对象，如上面的例子所示。如果你指定输出格式为xml或者kml，回应返回格式为XML或者VML。XML和VML这两种输出格式内容完全一致，唯一的不同只是MIME类型。

例如，这是地理译码器对"1600 amphitheatre mtn view ca"的回应。

 

    1600 amphitheatre mtn view ca

   

      200

      geocode

   

   

     

        1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA

     

     

       

          US

         

            CA

          

             Santa Clara

            

               Mountain View

              

                 1600 Amphitheatre Pkwy

              

              

                 94043

               

            

          

        

      

    

    

       -122.083739,37.423021,0

    

  

 

如果你更喜欢更短的回应以利于解析，而且不需要特定特性比如多个结果或者良好的格式，我们提供csv输出格式。csv格式的回应包含4个用逗号分隔的数字。第一个数字是状态代码，第二个是精确度，第三个是纬度，第四个是经度。下面是三个地址，按照精确度增量排序："State St, Troy, NY", "2nd st & State St, Troy, NY" and "7 State St, Troy, NY"

200,6,42.730070,-73.690570

200,7,42.730210,-73.691800

200,8,42.730287,-73.692511

错误排除

如果你的代码不能正常工作，这里有些步骤可能帮您解决您的问题：

·      确保你的API Key是正确的。

·      检查你的拼写。记住JavaScript是大小写敏感的语言。

·      使用JavaScript调试器。在Firefox下，你可以使用JavaScript控制台或者Venkman Debugger。在IE下，你可以使用微软脚本调试器。

·      搜索Maps API讨论组。如果你不能找到你问题的答案，发帖提问。

·      查看其他资源获取第三方开发者资源。

其他资源

这里有一些额外的资源。注意这些站点不属于Google。

·      Mapki一个关于Maps API的流行wiki，包括FAQ页面。

API纵览

API纵览描述了Maps API的核心概念。为了查看全部类和方法的列表，参看Maps API类参考。

GMap2类

GMap2类的实例用来在页面展现地图。你可以创建多个类的实例(一个地图一个)。当您创建了一个地图实例，您指定一个页面元素(通常是div元素)来包含这个地图。除非您明确的指定地图的尺寸，否则地图大小会取决于容器的尺寸。

GMap2类的方法可以控制地图的中心和缩放级别，添加删除覆盖对象(例如,GMarker和GPolyline)。还有方法可以用来打开一个信息窗口，就像你在Google Maps里面看到的。更多信息参看信息窗口。

更多GMap2类的信息,参看GMap2类参考。

事件

您可以利用事件监听器在您的程序里面加入动态元素。一个对象导出命名事件，您的程序可以用静态方法GEvent.addListener和GEvent.bind来"监听"这些事件。例如，这个代码片断在每次用户点击的时候显示一个警告框：

var map = new GMap2(document.getElementById("map"));

map.setCenter(new GLatLng(37.4419, -122.1419), 13);

GEvent.addListener(map, "click", function() {

  alert("You clicked the map.");

});

GEvent.addListener把一个函数当作第三个参数，用来指定时间句柄的相应函数。想把事件绑定到类实例的方法上，可以用GEvent.bind方法。在下面的例子里，应用程序类实例把地图事件绑定在他的方法上，在触发的时候修改类的状态：

function MyApplication() {

  this.counter = 0;

  this.map = new GMap2(document.getElementById("map"));

  this.map.setCenter(new GLatLng(37.4419, -122.1419), 13);

  GEvent.bind(this.map, "click", this, this.onMapClick);

}

 

MyApplication.prototype.onMapClick = function() {

  this.counter++;

  alert("You have clicked the map " + this.counter + " " +

        (this.counter == 1 ?"time" : "times"));

}

 

var application = new MyApplication();

显示范例 (bind.html)

信息窗口

每个地图有一个"信息窗口"用来浮在地图之上显示HTML内容。信息窗口看起来像一个漫画书的文字气泡；它包含一个内容区域和一个锥形箭头，锥形的箭头指向地图上的指定点。你可以在Google地图上点击一个标记，就可以看到信息窗口。

一个地图同时只能显示一个信息窗口，但你可以移动信息窗口，或者修改它的内容。

信息窗口的基本方法是openInfoWindow，需要提供一个点和一个HTML DOM元素作为参数。HTML DOM元素会被追加到信息窗口的容器内，而信息窗口的锥形箭头会指向给定的点。

openInfoWindowHtml方法很类似，只是它用HTML字符串作为参数而不是HTML DOM元素。

要在如标记之类的一个覆盖对象之上显示信息窗口的话，您可以设置第三个可选参数，信息窗口尖端和给定点之间的偏移量。所以，如果你的标记有10个像素那么高，你可以把点偏移量GSize(0, -10)传给方法。

GMarker类导出了openInfoWindow方法，可以处理你的图标形状和尺寸相应的偏移量，所以你不用担心如何自己去计算这个值。

更多信息请查看GMap2和GMarker的类参考。

覆盖对象

覆盖对象是覆盖在地图上有固定经纬度坐标位置的对象，所以当你拖动地图或者改变地图类型的时候，他们也会跟着移动。

Maps API支持两种类型的覆盖对象：标记，地图上的图标；折线，用一系列点形成的折线。

标记和图标

GMarker类的构造器有两个参数，一个是图标，一个是点，还支持一些事件，比如"点击"事件。参看overlay.html在地图上创建标记的一个简单例子。

创建标记最难的部分是指定一个图标，这很复杂是因为Maps API里的一个图标需要很多图片构成。

每个图标包含一个前景图片和一个影子。影子应该由前景图片倾斜45度(向右上方)构成，而影子图片左下角应该跟前景图片的左下角对齐。影子图片应该是24位的PNG图形格式背景应该透明，这样影子的边缘在地图上面才能正确显示。

GIcon类需要您在初始化图标的时候指定这些图片的尺寸，这样Maps API就能用恰当的尺寸来创建这些图片。这是创建一个图标所需的最小代码(图标来自Google地图)：

var icon = new GIcon();

icon.image = "http://www.google.com/mapfiles/marker.png";

icon.shadow = "http://www.google.com/mapfiles/shadow50.png";

icon.iconSize = new GSize(20, 34);

icon.shadowSize = new GSize(37, 34);

GIcon还有几个属性，如果设置就可以得到最大化的浏览器兼容性以及图标的功能性。例如，imageMap属性可以用来设定图标的不透明区域的形状。如果你不设定这个属性，在Firefox/Mozilla下整个图片范围(包括透明区域)都可以点击。更多的信息参看GIcon类参考。

折线

GPolyline类的构造器把一个点的数组作为参数，根据给定点的顺序创建连接这些点的一系列线段。您还可以指定这些线的颜色，宽度和透明度。颜色应该使用16进制数字表现，如#ff0000而不要用red。GPolyline类不能理解颜色名。

下面的代码片断创建两点之间10个像素宽的红色折线：

var polyline = new GPolyline([

  new GLatLng(37.4419, -122.1419),

  new GLatLng(37.4519, -122.1519)

], "#ff0000", 10);

map.addOverlay(polyline);

在Internet Explorer下，Google地图使用VML来画折线(更多信息请看XHTML和VML)。在所有其它的浏览器，我们从Google服务器请求线的图片覆盖在地图上，在地图缩放和拖动的时候刷新图片。

控件

想为您的地图加入缩放工具条之类的空间，请使用addControl方法。Maps API包括很多可以用在您的地图上的控件：

·      GLargeMapControl - 大号平移和缩放控件，位置是左上角。

·      GSmallMapControl - 小号平移和缩放控件，位置是左上角。

·      GSmallZoomControl - 大号缩放控件，位置是左上角。

·      GScaleControl - 地图比例尺。

·      GMapTypeControl - 选择地图类型的控件。

·      GOverviewMapControl New! - 位于屏幕一角可以收起来的概览图。

例如，如果想在您的地图上添加一个平移和缩放控件，您可以包含下面的这行代码：

map.addControl(new GLargeMapControl());

addControl方法有一个可选参数GControlPosition用于让您自己指定控件的位置。如果这个参数被省略，Maps API将采用控件的默认位置。这个例子加入一个地图类型空间到右下角留空10个像素的位置：

map.addControl(new GMapTypeControl(),

               new GControlPosition(G_ANCHOR_BOTTOM_RIGHT, new GSize(10, 10)));

更多信息请看GControlPosition类参考。

XML和RPC

Google Maps API用工厂方法(译注:设计模式)创建XmlHttpRequest对象，可以支持新版本IE，Firefox和Safari。下面的例子下载一个叫做myfile.txt的文件然后用JavaScriptalert函数显示这个文件的内容：

var request = GXmlHttp.create();

request.open("GET", "myfile.txt", true);

request.onreadystatechange = function() {

  if (request.readyState == 4) {

    alert(request.responseText);

  }

}

request.send(null);

API还引入了针对典型的HTTP GET请求的类似方法叫GDownloadUrl，不需要XmlHttpRequest的readyState检查。上面的例子用GDownloadUrl函数改写如下：

GDownloadUrl("myfile.txt", function(data, responseCode) {

  alert(data);

});

您可以用静态方法GXml.parse来解析XML文档，它仅用一个XML字符串当作唯一的参数。这个方法兼容大多数现代浏览器，而当他遇到不支持本地XML解析的浏览器它会抛出一个异常。