静态地图API开发人员指南.docx
《静态地图API开发人员指南.docx》由会员分享，可在线阅读，更多相关《静态地图API开发人员指南.docx（18页珍藏版）》请在冰豆网上搜索。
静态地图API开发人员指南
静态地图API开发人员指南
欢迎阅读Google静态地图API的开发人员文档！
通过Google静态地图API，您不需要使用JavaScript或加载任何动态页面，便可将Google地图图像嵌入到自己的网页中。
Google静态地图服务会根据通过标准HTTP请求发送的网址参数来创建您的地图，并将地图以您可以在网页上显示的图像形式返回。
Google静态地图API需要地图API密钥。
如果尚未注册地图API密钥，请注册一个免费的API密钥。
新！
Google静态地图API现在具有卫星和地形图块功能！
快速示例
以下示例包含静态地图图像的网址，如下所示：
#NotethatthisURLwrapsatthe'\'character.
#YoucancopytheURLfromtheimagebelow,however.
#Forclarity,wedon'twritetheactualAPIkeyinuse.
#
&markers=39.949328,116.3875,blues%7C39.949328,116.3775,greeng%7C39.943028,116.3975,redc\
&key=MAPS_API_KEY&sensor=false
请注意，您无需进行任何“特殊”操作便可在地图上显示此图像。
不需要JavaScript。
只需创建一个网址并将其放入![]()
标签中。
您可以将Google静态地图放在可放置图像的网页上的任何位置。
1.受众
2.使用限制
3.概览
4.网址参数
5.参数的用法
o指定位置
▪经度和纬度
▪地址解析
o缩放级别
o图像大小
o视口
o图像格式
o地图类型
o添加标记
▪标记描述符
▪使用标记隐式定位地图
o静态地图路径
▪路径属性
▪指定路径点
6.更多信息
读者
本文档适用于希望在网页中包含Google静态地图API图像的网站和手机开发人员。
它对使用有关可用参数的API和参考材料进行了介绍。
使用限制
使用静态地图API需要注册一个免费的地图API密钥。
地图API密钥允许您使用静态地图API和标准地图API。
使用Google静态地图API还需遵从每位查看者每天的唯一（不同）图像请求不超过1000次的查询限制。
由于此限制是按“查看者”而非“关键字”制订的配额，因此大多数开发人员并不需要为超过其配额而担心。
此外，请注意，一般情况下，对相同图像的请求，除了第一次，其他请求并不计入该限制。
如果用户超出以上的禁止限制，则将显示以下图像，指示超出了配额：
强制执行此限制是为了防止滥用和/或重复使用静态地图API。
以后可能对此限制进行更改，而无需另行通知。
如果超过了24小时的限制或滥用此服务，静态地图API会临时停止运行。
如果您继续无视这个限制，将会阻止您对静态地图API的访问。
概述
Google静态地图API通过网址返回图像（GIF、PNG或JPEG）来响应HTTP请求。
您可以为每个请求指定地图的位置、图像的大小、缩放级别、地图的类型以及可选标记在地图各个位置上的放置。
此外，您还可以使用字母字符为您的标记制作标签，以便在“关键字”中引用这些标记。
将静态地图API图像嵌入![]()
标签的src属性内的网页上。
当显示网页时，浏览器从静态地图API请求图像，并显示在图像位置内。
本文档介绍了静态地图API网址的所需格式和可用参数。
还提供了一些指定网址的提示和技巧。
网址参数
Google静态地图API网址必须为以下形式：
有些参数是必需的，而有些参数则是可选的。
根据HTTP请求的标准，所有参数均使用&（&）字符分隔。
参数列表及参数的可能值枚举如下。
静态地图API使用以下网址参数定义地图图像：
∙center（不显示标记时为必需）定义地图的中心，到地图各边缘的距离相等。
此参数采用一个用逗号分隔的{经度,纬度}对（例如，"40.714728,-73.998672"）来标识地球表面的唯一位置。
有关详细信息，请参见下面的经度和纬度。
∙zoom（不显示标记时为必需）定义地图的缩放级别，缩放级别确定地图放大的级别。
此参数根据所需的区域缩放级别来采用数字值。
有关更多信息，请参见下面的缩放级别。
∙size（必需）定义地图图像的矩形尺寸。
此参数采用valuexvalue形式的字符串，其中先表示水平像素，再表示垂直像素。
例如，500x400定义了一幅宽为500像素、高为400像素的地图。
如果您创建一幅宽为100像素或更小的静态地图，“由Google强力驱动”徽标的大小会自动缩小。
∙format（可选）定义生成的图像的格式。
默认情况下，静态地图API创建GIF图像。
有若干种可能的格式，包括GIF、JPEG和PNG类型。
使用哪种格式取决于您想要显示图像的方式。
JPEG通常提供更大程度的压缩，而GIF和PNG提供更多细节。
有关详细信息，请参见图像格式。
∙maptype（可选）定义要构造的地图类型。
有若干种可能的地图类型值，包括satellite、terrain、hybrid和mobile。
有关更多信息，请参见下面的静态地图API地图类型。
∙markers（可选）定义要在指定位置附加到图像的一个或多个标记。
此参数采用由管道字符（|）分隔的标记定义的字符串。
请注意，如果为地图提供标记，就无需指定（通常情况下必需的）center和zoom参数。
有关更多信息，请参见下面的静态地图标记。
∙path（可选）定义要在指定位置覆盖在图像上的单条路径，其由两个或两个以上的连接点组成。
此参数采用由管道字符（|）分隔的点定义的字符串。
请注意，如果为地图提供标记，就无需指定（通常情况下必需的）center和zoom参数。
有关详细信息，请参见下面的静态地图路径。
∙span（可选）定义地图图像的最小“视口”，以成对的纬度和经度表示。
静态地图服务采用该值并生成适当缩放级别的地图，以包含距地图中心点的所提供全部的span值。
请注意，生成的地图可能包含在经度或纬度上更大的边界，这取决于地图的矩形尺寸。
如果指定了zoom，则会忽略span。
∙frame（可选）指定生成的图像应由蓝色的边框框起来。
框架由5像素宽，不透明度为55%的蓝色边框组成。
∙hl（可选）定义用于在地图图块上显示标签的语言。
请注意，该参数仅支持部分国家/地区图块；如果请求的指定语言不支持图块集，则将为该图块集使用默认的语言。
∙key（必需）标识生成此网址请求的域的地图API密钥。
如果没有地图API密钥，可以注册一个免费的地图API密钥。
∙sensor（必需）指定请求静态地图的应用程序是否使用传感器来确定用户的位置。
对于所有静态地图请求，此参数都是必需的。
有关详细信息，请参见下面的传感器。
参数的用法
静态地图API相对来说易于使用，因为它只包含一个参数网址。
此部分介绍怎样使用这些参数构造您的网址。
指定位置
静态地图API必须能够精确标识地图上的位置，目的在于使地图处于正确的位置（使用center参数）和/或将任何可选地标放置到地图的各个位置上（使用·markers·参数）。
静态地图API使用经纬度值指定这些位置。
这些值共同标识“地址解析”位置。
如果您的设备使用“传感器”（例如GPS设备）来确定某个设备或用户的位置，您还必须在您的静态地图API请求网址内传递sensor=true。
如果您的应用程序不使用传感器，则传递sensor=false。
经度和纬度
使用逗号分隔的文本字符串内的数字定义经度和纬度，精确到6位小数。
例如，“40.714728，-73.998672”是有效的地址解析值。
精确到6位小数之后的部分将被忽略。
经度值基于其到英国格林威治（本初子午线所在地）的距离。
由于格林威治位于纬度51.477222，我们可以输入center值51.477222,0来使地图以格林威治为中心：
经纬度值必须与地球表面的有效位置对应。
纬度可以采用-90和90之间的任意值，而经度值则可采用-180和180之间的任意值。
如果指定了无效的纬度或经度值，您的请求将作为错误请求被拒绝。
地址解析
许多人不使用经度和纬度，而是使用“地址”来表示位置。
将地址转换为地理点的过程称为“地址解析”，将在Google地图API服务部分中详细讨论。
请注意，要直接使用地址解析服务，需要使用地图API密钥。
除了这个地址解析服务之外，您也可以使用其他服务（包括Google地图本身）来获取经地址解析后的经纬度值。
例如，您可以将某个地址输入到Google地图，并通过单击地图右上方的链接到该页面来确定其经地址解析后的位置。
将显示一个弹出式对话框，对话框内可复制的网址。
如果将该网址复制到浏览器中，您便可以查找ll参数中包含的地址解析值。
缩放级别
Google地图上的地图具有整数“缩放级别”，可定义当前视图的分辨率。
普通地图视图中，可以使用0（最低缩放级别，在地图上可以看到整个世界）到19（最高缩放级别，可以看到每个建筑物）之间的缩放级别。
Google地图将缩放级别0设为包含整个地球。
随后的每个缩放级别在水平和垂直尺寸上使精确度加倍。
Google地图API文档中提供了有关怎样执行此操作的详细信息。
注意：
并非地球上的所有位置都会显示所有的缩放级别。
缩放级别根据位置的不同而有所不同，因为地球上某些地区的数据与其他地区相比更加细化。
如果发送了并不存在任何地图图块的缩放级别请求，静态地图API将转而返回黑色图像。
下面的示例请求了两幅曼哈顿地图，center值相同，但缩放级别分别为12和14：
图像大小
可以检索的最大图像大小为640x640像素。
size参数采用具有两个值的字符串，这两个值由x字符分隔。
640x640是所允许的最大图像大小。
请注意，center参数与size参数相结合可隐式定义地图图像的覆盖区域。
下面的示例请求地球赤道上的某个“块”（缩放级别为1）：
以下示例请求100x100像素大小的小型地图，以相同的区域为中心。
请注意较小的Google徽标：
视口
图像可能通过传递span参数指定一个“视口”（按纬度和经度值定义，以度为单位）来显示提供的中心点周围的地区。
以这种方式定义最大视口免去了指定确切缩放级别的必要。
静态地图服务将span参数与size参数配合使用来构建适当缩放级别的地图，其中至少包括指定的视口限制。
以下示例请求一个方形地图，以0度经度和0度纬度为中心，宽度和高度为20度：
以下示例请求一个以曼哈顿为中心的地图，在两个方向显示1度的弧度。
请注意，因为该地图水平形成，在水平方向扩展4度，因此可以在垂直方向最少扩展1度。
图像格式
可以以若干种常见网络图形格式返回图像：
GIF、JPEG和PNG。
format参数采用以下值之一：
∙gif（默认）指定GIF格式。
∙jpg指定JPEG压缩格式。
∙jpg-baseline指定非渐进式JPEG压缩格式。
∙png8指定8位PNG格式。
∙png32指定32位PNG格式。
jpg和jpg-baseline通常提供最小的图像大小，但是这是通过“有损”压缩而实现，这将降低图像的质量。
gif、png8和png32提供无损压缩。
大多数JPEG图像都是渐进式，这意味着它们先加载“较粗糙的”图像，再随着更多数据的传入而优化图像分辨率。
这使图像在网页中能够迅速加载，是当前最普及的JPEG应用。
但是，JPEG的部分使用（尤其是打印）要求非渐进式（基线）图像。
在这种情况下，您可能想使用非渐进式的jpg-baseline格式。
地图类型
Google静态地图API以若干种格式创建地图，如下所列：
∙roadmap（默认）指定标准路线图图像，如Google地图网站通常所示。
如果未指定maptype值，默认情况下，静态地图API会使用roadmap图块。
∙mobile指定移动设备的路线图地图图像，它包含更多的特征和文本字体，从而能够以高分辨率在移动设备的小屏幕上方便地进行查看。
∙satellite指定卫星图像。
∙terrain指定自然地形地图图像，显示地形和植被。
∙hybrid指定卫星和路线图的混合图像，在卫星图像上显示主要街道和地址名称的透明层。
您可以在以下代码示例中查看路线图和移动设备这两种类型之间的区别。
请注意，这些地图也有frame=true。
以下示例显示了卫星地图类型和地形地图类型：
标记
markers参数定义要添加到地图图像中的一个或多个标记的集合。
此参数是一个由赋值集合定义的多达50个标记的列表：
markers=markerDescriptor1|markerDescriptor2|markerDescriptor3|...等。
请注意，标记描述符使用管道字符（|）相互隔开。
（注意：
如果正在对网址进行编码，管道字符在ASCII中也显示为%7C。
）
标记描述符
每个标记描述符都包含一个字符串，用于定义放置标记的位置和显示标记时使用的可视属性。
这些字符串包含以下变量值：
∙{latitude}（必需）指定纬度值，精确到6位小数。
∙{longitude}（必需）指定经度值，精确到6位小数。
∙{size}（可选）指定集合{tiny,mid,small}中的标记大小。
如果未设置size参数，标记将以其默认（常规）大小显示。
∙{color}（可选）指定集合{black,brown,green,purple,yellow,blue,gray,orange,red,white}中的一种颜色。
∙{alphanumeric-character}（可选）指定集合{a-z,0-9}中的一个小写字母数字字符。
请注意，显示alphanumeric-character参数时仅能使用默认和mid大小的标记。
tiny和small标记无法显示字母数字字符。
纬度和经度值定义标记在地图上的位置。
如果位置在地图之外，该标记将不会显示在构建的图像上。
大小、颜色和字母数字字符值可以定义标记的可视外观。
如果未指定大小值，标记会以其默认（常规）大小显示。
此外，只有常规大小的标记才能显示字母数字字符。
如果未指定值（或指定了错误的值），则标记会显示为默认的带点红色标记。
示例标记声明的格式为{latitude},{longitude},{size}{color}{alphanumeric-character}。
请特别注意，字符串的大小、颜色和字母数字字符值不用逗号隔开。
样本标记声明如下所示。
markers=39.949328,116.3875,blues|40.711614,-74.012318,tinygreen|40.713504,-74.005607,midyellowc&key=MAPS_API_KEY&sensor=true_or_false
此markers参数定义三个标记（用“|”字符分隔）：
40.702147,-74.015794处标为“S”的一个蓝色标记，40.711614,-74.012318处的一个小型绿色标记，以及40.713504,-74.005607（市政厅）处标为“C”的一个中等大小红色标记。
以下示例中显示了这些标记：
使用标记隐式定位地图
通常，您需要指定center和zoom网址参数来定义生成的地图的位置和缩放级别。
但是，如果提供了markers参数，您也可以改用静态地图API来隐式确定正确的中心和缩放级别，具体取决于对这些标记位置的估算。
如果提供两个或两个以上的标记，静态地图API将确定适当的中心和缩放级别，从而提供足够的边距以显示markers参数中包含的标记。
下面的示例包含与上面显示的标记相同的标记，但删除了center和zoom参数，使地图中心更接近两个目标标记的位置。
静态地图路径
path参数定义要在地图图像上覆盖的一条或多条路径的集合。
此参数是一个由赋值集合定义的路径列表：
path=pathColorType:
pathColorValue,weight:
pathWeight|pathPoint1|pathPoint2|pathPoint3|...等。
请注意，路径点使用管道字符（|）相互隔开。
（如果对网址进行编码，管道字符在ASCII中也显示为%7C。
）
路径属性
每个path参数的开头都可能是指定路径属性的可选字符串，由“pathColorType”和该类型的值组成（使用冒号分隔）。
如果需要默认的路径属性，可能忽略路径描述符中的路径属性前缀；在本例中，路径描述符的第一个参数描述路径声明中的第一个点。
（请参见下面的路径点。
）
有两种可能的“pathColorType”：
∙rgb指定标准的RGB颜色方案，使用0xffffff形式的24位十六进制值颜色值作为“pathColorValue”。
rgb路径的默认不透明度为50%。
∙rgba指定0xffffffff形式的32位十六进制颜色值作为“pathColorValue”，其中第四个字节（最后两个字符）指定“alpha通道”不透明度。
使用rgba使您可以更改您创建的任意路径的不透明度。
除了颜色，weight还指定给定路线的粗细（以像素为单位）。
部分示例路径定义显示如下：
∙蓝色细线，50%不透明度：
path=rgb:
0x0000ff,weight:
1
∙红色实线：
path=rgba:
0xff0000ff,weight:
5
∙黑色粗实线：
path=rgba:
0xffffffff,weight:
10
路径描述符中的具体路径属性为可选。
如果需要默认属性，您可以跳过定义路径属性；在这种情况下，路径描述符的第一个“参数”将由第一个声明点组成。
路径点
为了绘制路径，path参数也必须传递两个或两个以上的点。
Google静态地图API随后将沿着这些点按指定顺序连接路径。
每个“pathPoint”都以“pathDescriptor”表示，由|（管道）字符隔开。
和标记一样，Google静态地图API会根据提供的路径的隐式定位来尝试确定地图的默认中心和缩放。
当前，对于任何给定路径都有100点的限制。
下面的示例定义了一个从纽约联合广场到时代广场的蓝色路径，默认不透明度为50%。
请注意，我们不需要提供center或zoom参数。
具体path参数如下所示：
path=rgb:
0x0000ff,weight:
5|40.737102,-73.990318|40.749825,-73.987963|40.752946,-73.987384|40.755823,-73.986397
下面的示例定义了相同的路径，即定义不透明度为100%的红色实线：
具体path参数如下所示：
path=rgba:
0xff0000ff,weight:
5|40.737102,-73.990318|40.749825,-73.987963|40.752946,-73.987384|40.755823,-73.986397
升级会员 