Google Maps API

地图 API
- 开发指南
  - 基础
  - 事件
  - 控件
  - 叠加层
  - 服务
- 示例
- 参考

Mapplets API
- 主页
- 文档

Google 地图 API 概念

欢迎阅读 Google 地图 API 的开发人员文档！Google 地图 JavaScript API 允许您在网页中嵌入 Google 地图。要使用该 API，您需要先注册以获得 API 密钥。收到 API 密钥之后，即可以按照本文档中的说明开发地图应用程序。

本文档根据英文版 Google Maps API 2 编写。有关英文版的最新功能，请参见英文版 Google Maps API 2 文档。

请注意，为了使用中国的地图数据，您需要使用来自 ditu.google.com （或 ditu.google.cn）的 JavaScript 代码。申请 API 密钥时自动生成的代码缺省指向 maps.google.com。因此，您需要手动将其改为 ditu.google.com（或 ditu.google.cn）。另外， Google Maps API 2 的某些功能目前还不支持中国。

关于 Google 地图 API，请您在Google 地图 API 讨论组讨论交流。如果参与英文 Maps API 讨论组，请说明您使用的是中文版 Google 地图 API，以避免误解。

Google 地图 API 现在与 Google AJAX API 加载器集成，后者为加载和使用多个 Google AJAX API 创建了一个公共的框架。有关更多信息，请查阅如下所示的资料：

在 Google 地图 API 中使用 Google AJAX API 加载器。
Google AJAX API 文档

新！ Google Mapplets - 构建嵌入 Google 地图站点中的迷你应用程序。

面向的读者

本文档设计用于熟悉 JavaScript 编程和面向对象编程概念的人。您还应从用户的角度熟悉 Google 地图。网络上有许多 JavaScript 教程。

本文档是概念性文档，不一定完整和详尽；其目标是使您可以很快地开始使用 Google 地图 API 探索和开发很酷的应用程序。我们还发布了 Google 地图 API 参考，该文档相对比较完整。

我们最近重新组织了本文档，添加了更多概念性的信息，并将讨论的主题分为以下几个主要领域：

希望这种新设计便于阅读，尤其是对地图 API 比较陌生的开发人员。同时欢迎对本文档提出反馈。确保加入地图 API 开发人员论坛提供反馈并讨论 API。

创建 Google Mapplets

Google地图API 现在增加了对 Mapplets（地图加小程序，Map + Gadget）的支持，允许您在 Google 地图中嵌入外部托管的应用程序。这些 mapplets 在自己的 iFrame 中运行，允许您创建“杂烩的杂烩”（”mashups of mashups”），并可以混合使用一个网站和另一个网站的代码。这将在 Google 地图中创建一个全新的编码世界！编写 mapplet 很容易，尽管有些操作与在标准 Google 地图 API 中的操作不同。请参阅 Google 地图 Mapplet 文档和参考以了解更多信息。

使用 Google AJAX API 加载器

Google 地图 API 现在与 Google AJAX API 完全集成。此框架允许您为所有支持的 Google AJAX API 加载一个 API 密钥，还为每个 API 提供一个公共的名称空间，允许不同的 Google API 共同运行。不要担心：如果决定不使用 Google AJAX API 框架，仍可继续使用现有名称空间。

使用 Google AJAX API 框架相对简单。将应用程序更改为使用该框架包括以下步骤：

不是加载 http://ditu.google.com/apis 中的 API，而是加载 http://www.google.com/jsapi 中的公共加载器。可以将现有 Google 地图 API 密钥传递到以下网址：
```
<script type="text/javascript" src="http://www.google.com/jsapi?key=ABCDEFG"></script>
```
使用 google.load 方法加载所需特定 API。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(39.917,116.397), 14);
  }
  google.setOnLoadCallback(initialize);
</script>

有关使用 Google AJAX API 加载器的完整文档位于 http://code.google.com/apis/ajax/documentation/。

编程说明

开始钻研 Google 地图 API 之前，应注意以下问题，以确保应用程序可以在目标平台上顺利运行。

浏览器兼容性

Google 地图 API 支持与 Google地图网址相同的浏览器。脚本 http://ditu.google.com/maps?file=api&v=2 可以在几乎所有浏览器中正确解析，所以检查兼容性之前可以安全地包含该脚本。

有时不同的应用程序对使用不兼容的浏览器的用户需要展示不同的行为。地图 API 提供了一个全局方法 (GBrowserIsCompatible()) 来检查兼容性，但它检测到不兼容的浏览器时没有任何自动行为。本文档中的多数示例不检查浏览器兼容性，对旧版浏览器也不显示错误消息。很明显真正的应用程序应该对不兼容的浏览器设计更友好的行为，但我们忽略了此类检查以提高这些示例的可读性。

好的应用程序将不可避免遇到浏览器和平台之间不一致的情况。这些问题没有简单的解决方法，但 Google 地图 API 开发人员论坛、Google Maps API 讨论组（英文）和 quirksmode.org 都是可以用来查找变通方法的好资源。

XHTML 和 VML

我们建议在包含地图的页面上使用与标准兼容的 XHTML。当浏览器在页面顶部看到 XHTML DOCTYPE 时，它们会以“符合标准的模式”显示页面，使其布局和行为在跨浏览器时更可以预期。没有该定义的页面可能会以 Quirk 模式显示，这或许会产生不一致的布局。

如果要在地图上显示折线（类似于 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://ditu.google.com/maps?file=api&v=2 网址中的 v 参数表示 Google 地图 API 使用的版本号。多数API用户可能想通过在该网址中传递 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 版本大约每两周更新一次，一些开发人员更喜欢使用稳定的 v=2.s。请注意稳定版本可能比当前版本落后几个版本，因此也许不包含一些最新功能。

我们更新 API 时，其版本都会更新（例如“版本 2.76”）。当我们更新 API 时，基于先前版本的较旧代码可能偶尔会和声明的行为方式不同。如果一定需要将应用程序绑定在特定的 API 版本上，可以通过在 v 参数中明确包含该版本而执行此操作（例如，v=2.75）。但不建议这样做。将您的产品基于最新代码始终是最佳选择。

当将来对 API 进行重大更新时，我们将更改主版本号，并在 Google 代码和地图 API 开发人员论坛上发布声明。当发生这种情况时，我们期望同时支持这两个版本至少一个月，以允许您迁移代码。

地图团队还使用最新的错误修订和性能增强功能透明地更新 API。这些错误修订只会提高性能和修订错误，但我们可能会意外损坏某些 API 客户端。请使用地图 API 开发人员论坛报告此类问题。

升级 v1 应用程序

本文档讲述的地图 API 对应的是 2006 年 4 月 3 日投放市场的英文 Maps API 第 2 版。如果您使用的只是中国地图(站点 ditu.google.cn 和 ditu.google.com) API，则不需要担心，因为已经是第 2 版。如果您的 API 使用英文 Maps API 第 1 版（即在 2006 年 4 月 3 日开发的站点），则您应尝试更新您的网站。请参阅第 2 版升级指南以了解更多信息。

地图 API 中的示例

请注意本文档中的多数示例仅显示相关 JavaScript 代码，而不显示整个 HTML 文件。可以将 JavaScript 代码插入自己的框架 HTML 文件，或可以通过单击示例后的链接下载每个示例的完整 HTML 文件。

减少浏览器内存泄露

Google 地图 API 鼓励使用函数 closures，API 事件处理系统 GEvent 将事件与 DOM 节点相关联的方式几乎肯定会使一些浏览器（尤其是 Internet Explorer）泄露内存。 Maps API 的版本 2 引入了一个新方法 GUnload()，该方法删除导致这些泄露的多数循环引用。您应在页面的 onunload 事件中调用 GUnload()，以减少应用程序泄露内存的可能性：

<body onunload="GUnload()">

使用此函数可以在 Google 地图中完全消除 Internet Explorer 内存泄露，但是如果注意到内存消耗问题，应使用诸如 Drip 的工具在您自己的站点上测试内存泄露。

其他资源

下面是其他一些英文 Maps API 相关的资源，中文地图 API 类似。请注意这些站点不是 Google 拥有或支持的站点。

Google Mapki：Mapki
Google Maps API 教程：http://www.econym.demon.co.uk/googlemaps/
Esa 的 Google Maps API 示例： http://koti.mbnet.fi/ojalesa/exam/index.html
USNaviguide 的 Maps API 示例：http://maps.huge.info/examples.htm
Mark McClure 的编码折线示例： http://facstaff.unca.edu/mcmcclur/GoogleMaps/EncodePolyline/
Marcelo 的 Maps API 实验：http://maps.forum.nu/
Bill Chadwick 的 Maps API 演示：http://www.bdcc.co.uk/Gmaps/BdccGmapBits.htm

疑难解答

如果您的代码不起作用，下面是一些可以帮助您解决问题的方法：

确保您的 API 密钥有效。
如果想使用中文地图，请用 "ditu.google.com" 或 "ditu.google.cn" 代替 "maps.google.com"。
查找输入错误。记住 JavaScript 是区分大小写的语言。
使用 JavaScript 调试器。在 Firefox 中，可以使用 JavaScript 控制台、Venkman Debugger 或 Firebug 插件。在 IE 中，可以使用 Microsoft Script Debugger。
搜索地图 API 开发人员论坛或者英文 Maps API 讨论组（请说明使用的是中文版 Google 地图 API）。如果找不到可以回答您的问题的帖子，请将问题张贴到论坛，并包含出现问题的网页的链接。
请参阅其他资源以获取第三方开发人员资源。


例如，“ajax api”或“开源”