使用 Maps Static API 的最佳实践

Google Maps Platform 静态 Web API 是一系列连接 Google 服务的 HTTP 接口，用于生成可直接嵌入到网页中的图片。

本指南介绍了一些有助于设置图片请求和处理服务响应的常见做法。如需查看 Maps Static API 的完整文档，请参阅开发者指南。

什么是静态 Web API？

借助 Google Maps Platform 静态 Web API，您无需 JavaScript 或任何动态页面加载便可将 Google 地图图像嵌入网页。静态 Web API 会根据使用标准 HTTPS 请求发送的网址参数创建图片。

典型的 Maps Static API 请求通常采用以下格式：

  https://www.googleapis.com/staticmap/z/x/y?parameters

注意：所有 Maps Static API 应用都需要进行身份验证。详细了解身份验证凭据。

SSL/TLS 访问

对于使用 API 密钥或包含用户数据的所有 Google Maps Platform 请求，都必须采用 HTTPS 协议。通过 HTTP 发起并包含敏感数据的请求将被拒绝。

构建有效网址

您可能认为“有效”网址不言自明，但实际并非如此。例如，在浏览器地址栏中输入的网址可能包含特殊字符（例如 "上海+中國"）；浏览器需要先在内部将这些字符转换为其他编码，然后再进行传输。同样，任何生成或接受 UTF-8 输入的代码都可能会将包含 UTF-8 字符的网址视为“有效”，但同样需要先转换这些字符，然后再将其发送给网络服务器。该过程称为网址编码或百分号编码。

特殊字符

我们之所以需要转换特殊字符，是因为所有网址都需要符合统一资源标识符 (URI) 规范所规定的语法。实际上，这意味着网址必须只包含一个特殊的 ASCII 字符子集：大家熟悉的字母数字符号以及一些在网址内用作控制字符的预留字符。下表汇总了这些字符：

有效网址字符汇总
字符集字符在网址中的用法
字母数字 a b c d e f g h i j k l m n o p q r s t u v w x y z A B C D E F G H I J K L M N O P Q R S T U V W X Y Z 0 1 2 3 4 5 6 7 8 9 文本字符串、在 scheme 中使用 (http)、端口 (8080) 等
非预留字符 - _ . ~ 文本字符串
预留字符 ! * ' ( ) ; : @ & = + $ , / ? % # [ ] 控制字符和/或文本字符串

构建有效网址时，您必须确保网址只包含下表中显示的那些字符。让网址按照上述字符集使用字符通常会带来两个问题，一个是遗漏问题，一个是替换问题：

  • 您要处理的字符未包含在上述字符集内。举例来说，非英语字符（例如 上海+中國）需要使用上述字符进行编码。按照常见惯例，空格（网址内不允许使用空格）通常也使用加号字符 '+' 表示。
  • 字符在上述字符集内存在且属于预留字符，但需要按原义使用。例如，? 在网址内用于表示查询字符串的开头；如果您想要使用字符串“? and the Mysterions”，则需要对 '?' 字符进行编码。

所有要进行网址编码的字符都会使用一个 '%' 字符和一个与其 UTF-8 字符对应的双字符十六进制值进行编码。例如，UTF-8 中的 上海+中國 在进行网址编码后将变为 %E4%B8%8A%E6%B5%B7%2B%E4%B8%AD%E5%9C%8B。字符串 ? and the Mysterians 在进行网址编码后将变为 %3F+and+the+Mysterians 或 %3F%20and%20the%20Mysterians。

需要编码的常见字符

以下是一些必须进行编码的常见字符：

不安全的字符 编码后的值
空格 %20
" %22
< %3C
> %3E
# %23
% %25
| %7C

转换您通过用户输入获取的网址有时颇为棘手。例如，用户可能会输入“5th&Main St.”这样的地址。一般而言，您应该根据网址的组成部分来构建网址，将所有用户输入都视为原义字符。

此外，对于所有的 Google Maps Platform 网络服务 API 或静态网络 API，网址最多可包含 16384 个字符。对于大多数服务，很少出现接近这一字符数限制的情况。但请注意，某些服务具有的若干参数可能会导致网址较长。