google map api 开发快速入门.doc

Google Map开发整理
Google Maps API 是 Google 自己推出编程 API ，可以让全世界对 Google Maps 有兴趣的程序设计师自行开发基于 Google Maps 的服务，建立自己的地图网站。以下是我在 Google Maps API 开发过程中找到的一些 API 的编程资源，包括中文文档，中文说明，示例等等，希望对 Google Maps 编程感兴趣的程序员有所帮助。
　　中文资料部分 （包括中文的文档说明等，以下的网址都是中文内容。）
　　下面的关于 API 的中文文档
　　 Google Maps API 第 2 版中文文档 
　　 Google Maps API 第 2 版升级指南 
　　 Google Maps API 第 2 版类参考 
　　另外一个版本的 Google Maps API 2 中文文档 http://www.zmap.org/doc/maps/documentation/
　　 Google Maps API 第 1 版中文文档 
　　下面是关于 KML 文件的中文文档
　　 Google Earth KML 中文说明（一） 
　　 Google Earth KML 中文说明（二） 
　　 Google Earth KML 中文说明（基于 Google Earth 客户端版本 3.0 的 KML 版本 2.0 ） 
　　英文资料部分 （主要是 Google 官方的文档说明，如果觉得中文翻译的有问题，也可以看看这些原始内容。 )
　　 Google Maps API 官方网 
　　 Google Maps API 英文文档 
　　 Google Maps API 官方 Blog 
　　 Google Maps API 论坛 
　　 Google KML 的官方文档 
　　 Google API 官方网 
附： Google Map API 中文开发教程
Google Map API 中文开发教程最好的教程还是 google 官方的说明文档，而且配有详细的例子，供大家学习，下面是文档的英文原文连接 

目录包括
1. 面向的读者
2. 简介
1. “ Hello World ” 程序
2. 浏览器兼容性
3. XHTML 和 VML
4. API 更新
5. 地理译码
6. 行程规划和本地搜索
7. 标注管理
3. 示例程序
1. 基本操作
2. 地图移动及动画
3. 给地图添加控件
4. 事件处理函数
5. 打开气泡提示窗口
6. 地图覆盖物
7. 单击事件处理
8. 给标注增加气泡提示窗口
9. 多页的气泡提示窗口
10. 创建图标
11. 使用图标类
12. 可拖拽的标注
13. 编码折线
14. 在地图中使用 XML 和异步 HTTP 通信 (AJAX)

15. 自定义地图控件
16. 自定义地图覆盖物
1. 标注管理器示例
1. 天气预报图 

2. 疑难解答
1.
1. 其它资料
2. API 概览
1. GMap2 类 

2. 事件
3. 气泡提示窗口
4. 地图覆盖物
5. 控件
6. XML 和 RPC
7. 减少浏览器内存泄露
3. 演示程序
4. 类参考
     同步中文文档请参阅： http://www.codechina.org/doc/google/gmapapi/
谷歌地图API密钥（API Key）的解读和使用技巧 收藏
好了，通過前一篇的介紹，大家對Google Map都有所瞭解了吧。不過還得一步步的來。先瞭解API Key吧。所谓 API 密钥（ API Key ），其实就是一个字符串，在使用 script 标签导入 API 类库的时候作为请求参数传给谷歌的地图服务器，形式就是： 

我的API Key是：
ABQIAAAAMWyR7XvYN8KE9N6m_jcU4BRlfWJrPzRGiYSzS4l55_z1ea3VShRolPwARGHvivnEFRLVGXyIlsrYpA

    使用谷歌地图 API 的第一步就是要 注册一个 API 密钥 ， 谷歌的 API 使用条款 对这个密钥的用途有很正式的说明，其实总结起来也很简单： 
    1 、谷歌地图 API 提供的服务是免费的，对于通过 API 正常使用谷歌地图的网站基本没有任何限制； 
    2 、说 “ 基本 ” 没有限制的原因是，谷歌对每个 API 密钥对应的网站所作的 地理编码 / 地址解析 请求次数有限制，每天（ 24 小时）的请求次数不能超过 15000 次；
    3 、不能使用谷歌地图从事任何非法的行为，否则谷歌应该能够通过这个密钥阻止你的网站使用谷歌地图；
更简单的说，谷歌使用这个密钥保证能够对所有 API 用户 / 网站进行区分，方便必要的时候对 “超常规 ” 用户进行阻拦。 
    对于地址解析的次数限制，一般来说不会有什么影响，这里主要说 API 密钥，所以以后有时间可以再详细说说地址解析相关的东东。

    对于 API 密钥，还有几点需要记下来： 
    1 、如果使用 API 的页面还没有发布，只是在本地调试，可以不用密钥，随便用个字符串代替就可以了； 
    2 、 API 密钥只对网站目录或者域有效，所以，虽然你是使用同一个谷歌帐号登录后注册的密钥，但是，对不同域的网页，需要用这些域分别注册不同的密钥，对于同一个域里的页面，直接拿你网站的域名注册一个，在这个域里的所有页面就可以通用这个密钥了。

    还有一个关于 API 密钥的实际问题： 
    在论坛里还有人问过，同一个页面需要支持不同的域名，最简单的就是公司有一个 cn 域名，也有一个 com 域名，这怎么办？ 
    其实，对于这种问题，可以提前先注册好不同域名对应的密钥，存在你的JS 变量里面，页面加载时通过window.location 得到当前请求页面的域名，通过这个域名在找到对应的密钥，然后使用script 动态加载的方法加载地图API ，用代码描述就是：
    // 事先已经注册好的密钥
    var keyMapping = {host1:key1, host2:key2};
    // 实际请求页面的域名
    var requestHost = window.location.hostname;
    // 找到需要的密钥
    var key = keyMapping[requestHost];
    // 构造加载API 的script url
    var apiUrl = " + key;
    // 使用script 动态加载的方法加载地图API
    var scriptTag = document.createElement('script');

    scriptTag.setAttribute('type', 'text/javascript');
    scriptTag.setAttribute('src', apiUrl);
    document.getElementsByTagName('head')[0].appendChild(scriptTag);
    使用这段代码时，需要注意把你自己的JS 代码中对API 的各个类的调用放在API 加载完成以后，详细的解释可以先google 一下著名的DomReady 的问题 ，三言两语还是说不清楚的，呵呵。
    这段代码我没有实际跑过，欢迎斧正，如果你有更好的方法，我更愿意洗耳恭听了。
使用谷歌地图API应该有所了解的一些技术外背景 收藏
这些内容，常用谷歌地图的应该也都知道，我也只写我知道的，了解这些对使用 API 还是有帮助的。
1 、 谷歌地图主页 
    谷歌地图对应不同的地区都会有一些专门的主页，首次登陆时会显示这些地区，比如，香港的： .hk ，台湾的： .tw ，日本的： http://maps.google.co.jp 

    不过，我们常用的也就三个： 
        这个应该是谷歌地图的全球主页，默认显示老美地图，拖拽到不同地区会对应显示不同语言版本的地图，不过目前对中文数据搜索支持的不如下面正式的中文主页； 
        这个么，我叫它是谷歌地图的中文主页，什么意思看下一个你就知道了，用这个可以使用 “ 我的地图 ” ； 
        这个，我叫他是谷歌地图的大陆主页，目前还没有 “ 我的地图 ” 这个功能； 
    后面这两个主页只能显示大陆地区的详细地图，如果想看别的地区的，就只能用全球主页了。 
    当然，别以为你抓着漏洞可以注册个  ，然后卖给谷歌，不信你试试 ，看它跳到哪里了 :)
    2 、谷歌地图的类型 
    其实，谷歌地图的类型主要也就三种： 
    普通地图：历史悠久的人工绘制地图，不多说了，不知道的给我留个地址，我快递个板砖给你； 
    卫星地图：用卫星图片拼成的地图，不同地图的显示精度有区别，现在中文主页上也有了，曾经可是被禁止的，怕你偷看海南的黑鱼； 
    地形地图：用等高线标出海拔的地图，对地理教学和教育相关的相当有用，当然，对军迷也超级有吸引力，不展开 !
    把这三种组合起来 ( 主要是普通地图和卫星地图的组合 ) ，或者在这些地图上添加其他的数据，就又有一些新的类型了，这个层出不穷，我只说主页上现有的： 
    混合地图：就是把普通地图和卫星地图结合，在卫星地图上显示行政区、街道等等，在全球主页上把鼠标移到 “ 卫星 ” 按钮上，会跳出来一个 “ 显示标签 ” 的复选框，选中后地图就是这个类型了，中文还没支持，不知道什么时候可以用； 
    交通地图：在地图上显示交通信息。这个理论上是实时的，不过，在目前的中文地图上，吸引眼球的作用更大一些，如果能在手机版上使用就好了（貌似目前还没有），而且只有北京和上海有数据支持； 
    街景地图：这个和交通地图一样，严格上不算是一种地图类型，就是使用 Flash 来显示街道的全景图，我也在等中文地图支持街景了（中文 API 已经支持 StreetView 相关的类了，就是没有数据），不久前看到的消息是目前谷歌对这个没有时间表，呵呵，他是 “ 万事俱备，只欠东风 ” ，努力吧！ 
    在地图 API 中，后面组合的这三种除了混合地图算作是一种地图类型外，其他两个都不算是地图类型，被看着是在地图上新增的层（术语：叠加层 /overlay ）。
    3 、谷歌地图的数据源 
    谷歌是一个服务提供商，而不是一个内容提供商，所以，准确的说，谷歌地图向终端用户提供的是基于地图的搜索服务。从这一点上，可以把谷歌地图上的数据分为三类： 
    地理数据：地理、空间信息，包括经纬坐标、航拍 / 卫星图片、行政区划以及据此绘制的图片等等，由谷歌或其合作伙伴持有； 
    商业数据：与地理相关的商业数据，比如餐馆、影院、交通、景点等等，这也是由谷歌或其合作伙伴持有，谷歌可能对这些数据有一个采集、过滤、整理的再加工过程。想被客户搜索到，就来这里 标注自己的公司 吧； 
    用户数据：用户使用谷歌地图 API 定制地图并在地图上标注的数据，这些数据由用户持有。 
     这样，通过这个分类，我们可以解决两个非常常见的疑问： 
    1 ）使用谷歌地图 API ，地图上的数据存在哪里？ 
      你是你的我是我的。是谷歌提供的数据，由谷歌负责；如果是你自己提供的数据，当然由你负责保存，谷歌相当于给你一个展示数据的平台，除非你愿意把自己的数据无偿贡献给谷歌 :)
    2 ）使用谷歌地图 API ，终端用户会通过谷歌搜索到我的数据吗？ 
      对谷歌地图来说，他的数据源只有地理数据和商业数据，所以在谷歌地图主页上不会搜到你的数据。但是，你可以在你的地图上定制谷歌搜索的数据源，使得用户可以搜索你的数据。（不是很肯定的哦，要看你的具体情况的）
    4 、 谷歌地图 API 
    谷歌地图 API 就是一系列使用 OO 方式组织的 JavaScript 类和静态方法（我有时候也统称为地图 API 类库），通过创建这些类的实例（对象）或调用 API 中提供的静态方法，可以在页面上创建和控制地图，也可以在地图上展示任何非谷歌提供的数据 / 信息。谷歌地图 API 只涉及浏览器 / 客户端相关的技术，比如 JavaScript 、 HTML DOM 、 CSS 等不涉及任何服务器端的技术，或者说，你可以基于任意你需要的服务端使用谷歌地图 API （所以，这里面能够展开的东东就太多了，以后再总结吧，我也在学习）。

加载谷歌地图API的URL详细解读 收藏
谷歌地图的 API 类库是通过 script 标签导入的，形式如下：   

    我们使用API 的时候关心的就是这个script 的src 属性了，这个属性也就两个部分：路径： ； 参数：file=api&hl=zh-CN&v=2&key=abcdefg 。
    解剖一下：
    1 、 路径： 
路径在这里需要注意的就是它的域名：  。
这个和 谷歌地图简单背景 里介绍的谷歌地图主页的问题类似，就是说，我们主要可以使用  、  、  这三个域名，有些区别和说明：
    1 ） 如果你需要在地图上显示大陆以外的详细地图，就非  莫属了，不过，这个域名对国内地理数据的查询 ( 比如查询地址、路线等等 ) 支持能力有限，如果你这方面有需求就要小心了，而且，这个应该是使用的国外的服务器，所以，访问速度也需要注意；
    2 ）相反，如果你需要使用谷歌提供的与国内地理数据查询相关的 API ，就是用  吧，使用这个域名的缺点就在于它和  提供的类库不是完全一致更新稍微有点滞后，而且，受限于国内数据源在法律等方面的限制，有些功能方面的支持也会受限，比如地址解析（现在已经放开了，这里只是拿来举例）；
    3 ）至于  和  的区别，我也很糊涂，如果你很想做个听话的好公民，不出一丝差错，那么 .cn 可能会比 .com 更让你放心一点吧，臆测，呵呵。
    总得来说，一般的应用使用  就可以了，如果需要使用大陆以外的详细地图，就考虑使用  吧。不过，因为使用了相同的命名空间，这两者在一个页面中不能共存，所以，可以考虑用两个 iframe 来动态切换，这里有个 火炬传递 的例子，就是这么实现的，咱当初也贡献过一把。

    2 、 参数：file=api&hl=zh-CN&v=2&key=abcdefg
    1 ） file=api 
         这个是请求API 的JS 文件用的，少不了，不需多说；
    2 ） hl=zh-CN 
         这个是在设定地图上除了地图图片以外的诸如控件名称、版权声明、使用提示等所需要显示文本的语言版本时候用的，如果没有指定这个参数就使用 API 的默认值，对  来说，默认是中文简体，  默认的是英文。其他的语言版本在这里有一个 简单的英文说明 （好像好久没更新了）。
    3 ） v=2 
         这个是用来指定需要导入的 API 类库的版本号，可以有四种设定方式：
         v=2.s   稳定版本，更新最慢，但是最可靠； 
         v=2     当前版本（只用主版本号），更新速度和可靠性介于 s 和 x 之间； 
         v=2.x   最新版本，更新最快，包括最新功能，可能没有当前版本可靠； 
         v=2.76 指定版本。不建议使用。 
         目前谷歌地图 API 的主版本号是 2 ，这是从 2006 年 4 月开放的版本，对之前的第 1 版做了一些比较重要的升级，不过估计国内用第 1 版的应该很少，所以也没必要多说了，注意第二版里定义地图对象时使用 GMap2 而不是 GMap 就可以了，否则可能会导致一些奇怪的问题，我是见过这样的。 
         多罗嗦两句，谷歌地图 API 正常情况下还是相当稳定的，不过也有一些比较著名的 Bug ，比如超长的 Polyline 在某些特定环境下可能会显示不正常。万一有什么问题可以去这里 找找是不是别人报过的 Bug （英文版），当然，更简单的办法是到谷歌地图 API 论坛里问问，不过别忘了把你的问题、运行环境描述清楚。我碰到过很多次这样的情况：对 JavaScript 或者浏览器端的某些技术特性不是很了解，出了一些奇怪的问题，撂一句话就走人，唉，就不评论了， “ 活到老学到老 ” 还是很有道理的。 
     4 ） key=abcdefg
         这个是设定你注册的 API 密钥，我 在这里费了不少口舌 ，不是很了解的话可以看看。

使用JavaScript创建地图步骤详解 
一段经过精简的代码： 

    etElementById 找到这个元素。
      容器的 style 属性在这里是用来定义这个容器的大小，从而决定所显示地图的大小，当然，如果你在这里不定义也可以通过其他的手段来达到目的，这里暂且先认为这个 style 的定义和 id 属性一样也是必不可少的吧。 
      其实 body 元素在这里也有一些特殊的作用，就是保证下一步骤在页面的 html 元素全部加载结束后再执行，详细的理论就不细说了。 
3 、定义你自己的 script 区域，在里面 new 一个 GMap2 对象，并且指定其显示所需的两个基本要素：中心、缩放层次。 

         var map = new GMap2(document.getElementById("mapContainer"));
         map.setCenter(new GLatLng(33.0, 106.0), 3);

     这里的GMap2 是谷歌地图API 中最重要的核心类，对应在页面上显示的地图，所有对地图的操作都需要在已经创建（new ）了GMap2 对象的基础上才能够进行。在调用GMap2 构造函数是使用的参数就是在上一步定义的地图容器，DOM 对象，使用document.getElementById 获取。
     要在页面上正常显示地图，仅仅调用 GMap2 类的构造函数创建一个 GMap2 对象还不够，你还需要指定这个 GMap2 对象的中心，通常也顺便指定它的缩放层次，否则就会默认显示缩放层次为 0 。 
     要指定新创建地图的中心，需要使用地图 API 里面定义的另一个常用类 GLatLng ，可以把这个类简单的认为是对地理坐标的封装类，构造函数中第一个参数是南北向的纬度，第二个参数是东西向的经度。 
     调用 GMap2 的 setCenter 方法设定完地图的中心和缩放层次，这个地图就可以正常显示了。

还需要关心的几个问题： 
    上面的示例代码仅仅是为了显示一个试验性质的简单地图，所以把很多暂时不是很必要的代码都去掉了，如果你需要创建具有很好的兼容性、并且能够发布到你自己的网站上的地图，还需要注意这几个问题： 
    1 、为了保证有足够的兼容性，谷歌建议使用 XHTML 来定义显示地图的 html 页面，所以，你需要在这个页面的顶部声明 XHTML 的 DOCTYPE ，并且在 html 中声明 XHTML 的命名空间 
       tp://www.w3.org/TR/xhtmll/DTD/xhtmll-strict.dtd">

      当然，最好你自己的页面代码也能够符合 XHTML 的语法规则。相对我们现在的 HTML4.01 来说，可以把 XHTML 语法规则简单的归纳如下： 
      html 、 head 、 title 、 body 元素一个都不能少，并且只能有 html 一个 root 元素； 
      不要使用简化的属性，必须使用 “name='value'” 的形式； 
      标签名和属性名都用小写字母，属性值要用引号括起来； 
      标签必须是闭合的，并且不能交叉嵌套； 
      使用 id 属性而不是 name 属性来获取元素；

    2 、为了兼容 “ 伟大的 ”IE 浏览器，以便能够在 IE 中也正确显示地图中的折线，需要在 html 标签中增加对 VML 命名空间的声明 

        这个很容易忽略，导致你在 IE 里的折线不能正常显示，所以把这一点单列出来加以强调。

    3 、对于通用的浏览器兼容性检查，地图 API 提供了一个全局方法 GBrowserIsCompatible()来保证地图 API 是在它所兼容的浏览器里运行的，这个兼容浏览器列表我也没找到最新的，谷歌文档里给出了一个远古时代的列表，所以不列也罢，对我们目前通用的 FireFox 、 IE 、 Safari 、 Opera 浏览器里运行地图 API 都没有问题。 
      这里只说一下GBrowserIsCompatible() 这个方法的使用：
      从名字也可以看出，GBrowserIsCompatible() 方法返回一个boolean 类型的值，所以，把我们对地图操作的起点放在对这个方法返回值的判断块中，形如：
      if(GBrowserIsCompatible()){
        // 开始创建和操作地图
      } else {
        // 如果有必要，就在这里定义你对这个异常的处理
      }
      当然，在你自己的代码中，针对不同的浏览器环境你还是需要自己实现兼容性的代码，这里的GBrowserIsCompatible() 只是保证地图API 类库是在它兼容的环境中运行的。
    4 、注册你要发布页面所在网站的谷歌地图 API 密钥，替换掉示例代码里的 key 我 在这里详细解释过这个密钥 ，不多说了。 
    5 、为了保证你的页面在任何可用的网络环境下都能快速加载并且正确显示，建议定义 body 元素的 onload 方法，在 onload 方法中开始你的 JS 动作。同时，把读入地图 API 的 script 标签放在 head 元素中，而把你自己的 JavaScript 代码块放到 body 标签的后面去定义。如果对浏览器的加载顺序比较熟悉的话，你就不必遵守我说的规则了，自由定义你认为应该的 JavaScript 声明顺序。 
    6 、为了避免 JavaScript 中引用页面的 DOM 元素可能存在的内存泄漏 ( 尤其是在 “ 伟大的 ”IE 浏览器中 ) ，你需要使用地图 API 中定义的 GUnload() 方法作为你的 body 元素的 onunload 方法，并且最好把这个作为一个必须的规则记住。但是 GUnload() 方法不是避免内存泄漏的大力丸，所以，你在自己的代码中还是需要注意避免内存泄漏这个问题。 
    7 、为了能够在页面上正常显示中文，需要把页面的字符集定义为 utf-8 。

    所以，一个完整的应用谷歌地图API 的页面代码如下：
           "http://www.w3.org/TR/xhtmll/DTD/xhtmll-strict.dtd">

          我的谷歌地图

      </head>

        线等等，那么，使用这个方法来嵌入谷歌地图是最简单的。 
      登录 谷歌地图主页 ，定位你需要显示的范围后，点击地图左上角的 “ 链接 ” ，会出现一个信息框，给出两个输入框，把第二个输入框中的内容拷贝到你的页面上就可以了。 
      其实，这段嵌入代码就是一个 iframe 的声明，所以，虽然地图主页提供一个自定义地图并预览的功能，但是只能自定义地图的大小，如果需要的话，我们完全可以通过手动修改这个 iframe声明来实现更多的自定义，比如，给这段 iframe 加上自定义的样式。 
2 、最精简的方法 —— 使用谷歌静态地图 
      如果你需要显示某个特定范围的地图而且需要在地图上加上一些标记、折线。但是，你并不在乎你网页上的地图能否拖拽，那么，这个静态地图应该就是你需要的了。 
      所谓静态地图，意思就是你在页面上嵌入的其实只是一个 GIF 图片，这个 GIF 图片是你通过URL 从谷歌动态获取的，这样的嵌入地图就有别于我们常用的 “ 动态 ” 地图了，而且，加载这样的地图，比加载一个完整的地图要快捷的多。 
      要在你的页面上使用这样的静态地图，只需要使用一个 img 标签，把这个标签的 src 属性指定为谷歌静态地图的 url 就可以了。 
      看一个简单的静态地图 URL ： 
      在这个 URL 中，你可以编辑 center 、 zoom 、 size 这些参数来指定地图的中心点、缩放级别、地图大小等等，当然，如果需要在地图上添加标记、折线，你还可以加上对应的参数。不过，不用担心你要记住这么多参数，这里有一个 定制静态地图的向导 ，简单的几步就可以得到你需要的 URL 了。如果有兴趣，可以去研究一下 谷歌静态地图的 API 文档 。 
      严格来说，谷歌静态地图也是谷歌地图 API 的一种，所以，使用静态地图是需要你的谷歌地图API 密钥的，如果你之前定义过地图 API 的密钥，直接 copy 过来就可以了，不需要再去注册。如果你不知道密钥是怎么回事，那就看看 我之前对密钥的解读 吧。 
3 、最自由的方法 -- 使用谷歌地图 API 
      如果上面两种方式都不能满足你的需求，那么，就来试试 谷歌地图 API 吧。虽然谷歌地图 API 已经细分为 JavaScript 、 Flash 、 Earth 、 Static 等等多个版本，但是，在我看来， JavaScript API 是谷歌地图 API 的根本，所以，在我的博客里，除非特别指明，说到谷歌地图 API 都是指谷歌地图 JavaScript API 。使用这个 API ，你可以用你愿意的任何可行的表现形式在地图上展现你的数据，甚至可以把你自己的地图做的比谷歌地图还漂亮。 
      要使用这个API 在页面中嵌入地图，简单的步骤就是：
      1 ）使用JavaScript 标签导入地图API 类库；
      2 ）在页面上定义一个装载地图的元素，通常使用一个div 标签，指定width 和height;
      3 ）在你的JavaScript 代码中new GMap2(document.getElementById("your map container's id"));
      4 ）使用GMarker 、GPolyline 等API 中提供的类定制你要在地图上添加的标记、折线等等。
      详细的创建谷歌地图过程可以看看我的 “ 使用 JavaScript 创建地图步骤详解 ” 。但是，要想自如的使用这个 API ，你需要具备一定的 JavaScript 知识和动手能力，此外，强烈建议你先读读谷歌地图 JavaScript API