Google Geocoding API---地理编码与反向地理编码
什么是地理编码
地理编码是将地址（如“1600 Amphitheatre Parkway, Mountain View, CA”）转换为地理坐标（如纬度 37.423021 和经度 -122.083739）的过程，您可以根据该地理坐标放置标记或定位地图。Google Geocoding API 可让您通过 HTTP 请求直接访问地理编码器。此外，该服务还可让您执行反向操作（将坐标转换为地址）；此过程称为“反向地理编码”。
使用限制
使用 Google Geocoding API 时，每天发送的地理位置查询请求不得超过 2,500 个。（Google Maps API for Business 用户每天最多可执行 100,000 个请求。）执行此限制是为了防止滥用和/或出于其他目的使用 Geocoding API，并且此限制以后可能会在不另作通知的情况下发生变化。此外，我们还设定了请求速率限制，以防滥用此服务。如果您超出了 24 小时限制或以其他方式滥用此服务，Geocoding API 可能会临时停止运行。如果您继续超出此限制，那么系统将阻止您访问 Geocoding API。
注意：Geocoding API 只能与 Google 地图配合使用；不得只进行地理编码而不在地图上显示结果。有关允许的用法的完整详情，请参阅 Maps API 服务条款许可限制。
地理编码请求
Geocoding API 请求必须采用以下形式：
http://maps.googleapis.com/maps/api/geocode/output?parameters
其中，output 可以是以下两个值中的任意一个：
-
json（推荐），用于表示以 JavaScript 对象表示法 (JSON) 的形式输出 -
xml，用于表示以 XML 的形式输出
要通过 HTTPS 访问 Geocoding API，请使用以下形式：
https://maps.googleapis.com/maps/api/geocode/output?parameters
如果应用包含敏感的用户数据（例如用户所处位置），建议您在请求中使用 HTTPS。
在这两种情况中，有些参数是必填的，有些则是可选的。根据网址的标准，所有参数均使用和号字符 (&) 进行分隔。下面的列表枚举了这些参数及其可能的值。
必填参数
-
address：要进行地理编码的地址。
或
latlng：您希望获取的距离最近、便于用户理解的地址的纬度/经度文本值。有关详情，请参阅反向地理编码。
或
components：您希望为其获取地理编码的组成部分过滤器。有关详情，请参阅组成部分过滤。如果提供了address，那么也接受作为可选参数的组成部分过滤器。 -
sensor：用于表示地理编码请求是否来自装有位置传感器的设备。该值只能是true或false。
Maps API for Business 用户必须在地理编码请求中添加有效的 client 和 signature 参数。有关详情，请参阅 Maps API for Business 网络服务。
可选参数
-
bounds：要在其中更明显偏向地理编码结果的视口的边框。该参数只会对地理编码器返回的结果产生影响，而不能对其进行完全限制。（有关详情，请参阅下面的视口偏向。） -
language，即返回结果时所使用的语言。请参阅支持的区域语言列表。请注意，我们会经常更新支持的语言，因此该列表可能并不详尽。如果未提供language，那么地理编码器将尝试尽可能使用发送请求的区域的本地语言。 -
region：即区域代码，已指定为 ccTLD（“顶级域”）双字符值。该参数只会对地理编码器返回的结果产生影响，而不能对其进行完全限制。（有关详情，请参阅下面的区域偏向。） -
components：组成部分过滤器，以竖线 (|) 进行分隔。每个组成部分过滤器均由一对component:value构成，并且会完全限制地理编码器返回的结果。有关详情，请参阅下面的组成部分过滤。
地理编码响应
返回的地理编码响应格式由网址请求的路径中的 output 标记指定。
JSON 输出格式
在此示例中，Geocoding API 针对关于“1600 Amphitheatre Parkway, Mountain View, CA”的查询请求了一个 json 响应：
http://maps.googleapis.com/maps/api/geocode/json?address=1600+Amphitheatre+Parkway,+Mountain+View,+CA&sensor=true_or_false
在此示例中，我们将 sensor 参数设为变量“true_or_false”，以强调您必须将该值明确设置为 true 或 false。
此请求返回的 JSON 如下所示：请注意，实际的 JSON 可能包含较少的空白。您不应假定请求之间的空白数量或格式。
{
"results" : [
{
"address_components" : [
{
"long_name" : "1600",
"short_name" : "1600",
"types" : [ "street_number" ]
},
{
"long_name" : "Amphitheatre Pkwy",
"short_name" : "Amphitheatre Pkwy",
"types" : [ "route" ]
},
{
"long_name" : "Mountain View",
"short_name" : "Mountain View",
"types" : [ "locality", "political" ]
},
{
"long_name" : "Santa Clara",
"short_name" : "Santa Clara",
"types" : [ "administrative_area_level_2", "political" ]
},
{
"long_name" : "California",
"short_name" : "CA",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "United States",
"short_name" : "US",
"types" : [ "country", "political" ]
},
{
"long_name" : "94043",
"short_name" : "94043",
"types" : [ "postal_code" ]
}
],
"formatted_address" : "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
"geometry" : {
"location" : {
"lat" : 37.42291810,
"lng" : -122.08542120
},
"location_type" : "ROOFTOP",
"viewport" : {
"northeast" : {
"lat" : 37.42426708029149,
"lng" : -122.0840722197085
},
"southwest" : {
"lat" : 37.42156911970850,
"lng" : -122.0867701802915
}
}
},
"types" : [ "street_address" ]
}
],
"status" : "OK"
}
请注意，JSON 响应包含两个根元素：
-
"status"，其中包含请求中的元数据。请参阅下面的状态代码。 -
"results"，其中包含一个经过地理编码的地址信息和几何图形信息的数组。
对于地址查询，地理编码器通常只会返回 "results" 数组中的一个条目，不过在进行模糊地址查询时，可能会返回多个结果。
请注意，如果您希望从结果中提取值，那么通常需要对这些结果进行解析。解析 JSON 相对来说较容易。有关一些建议设计模式，请参阅解析 JSON。
XML 输出格式
在此示例中，Google Geocoding API 针对上述同一关于“1600 Amphitheatre Parkway, Mountain View, CA”的查询请求了一个 xml 响应：
http://maps.googleapis.com/maps/api/geocode/xml?address=1600+Amphitheatre+Parkway,+Mountain+View,+CA&sensor=true_or_false
此请求返回的 XML 如下所示：
OK street_address 1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA 1600 1600 street_number Amphitheatre Pkwy Amphitheatre Pkwy route Mountain View Mountain View locality political San Jose San Jose administrative_area_level_3 political Santa Clara Santa Clara administrative_area_level_2 political California CA administrative_area_level_1 political United States US country political 94043 94043 postal_code 37.4217550 -122.0846330 ROOFTOP 37.4188514 -122.0874526 37.4251466 -122.0811574
请注意，该 XML 响应包括一个
-
-
请注意，此响应所花费的时间远远多于 JSON 响应。因此，除非您的服务出于某些原因需要 json，否则建议您将 xml 用作首选的输出标记。此外，请谨慎处理 XML 树，以便引用正确的节点和元素。有关用于输出处理的一些建议设计模式，请参阅使用 XPath 解析 XML。
本文档的其余部分将会使用 JSON 语法。在大多数情况下，对于说明本文档中的概念或字段名称，输出格式并不是很重要。不过，请注意以下细微差别：
- XML 结果会包含在一个根
- JSON 通过复数形式的数组 (
types) 来表示多个元素的条目，而 XML 则使用多个单数形式的元素 ( - 空白元素会在 JSON 中通过空数组来表示，而在 XML 中则表示为没有此类元素。例如，未生成任何结果的响应将会在 JSON 中返回一个空的
results数组，而在 XML 中则表示为没有
状态代码
地理编码响应对象中的 "status" 字段包含了请求的状态，并且可能会包含调试信息，以帮助您找到地理编码服务未正常工作的原因。"status" 字段可能包含以下值：
-
"OK"，用于表示未发生错误；已成功进行了地理编码且至少返回了一个地理编码结果。 -
"ZERO_RESULTS"，用于表示地理编码成功，但未返回任何结果。如果地理编码过程中传递的偏远位置address或latlng并不存在，就会出现这种情况。 -
"OVER_QUERY_LIMIT"，用于表示您超出了自己的配额。 -
"REQUEST_DENIED"，用于表示您的请求遭拒，这通常是由于缺少sensor参数。 -
"INVALID_REQUEST"，通常用于表示缺少查询内容（address或latlng）。
结果
当地理编码器返回结果时，会将其放在一个 (JSON) results 数组中。即使未返回任何结果（例如，如果地址不存在），地理编码器仍然会返回一个空的 results 数组。（XML 响应不包含或包含多个
一个典型的结果由以下字段组成：
-
types[]数组，用于表示返回的结果类型。此数组包含一个或多个标记，这些标记用于标识结果中返回的地图项类型。例如，“Chicago”的地理编码返回“locality”，表示“Chicago”是一个城市；同时返回“political”，表示它是一个政治实体。 -
formatted_address是一个字符串，其中包含该位置的可人工读取地址。通常该地址就相当于“邮政地址”，有时会因国家/地区的不同而存在差异。（请注意，部分国家/地区会有许可限制，不允许发布完整的邮政地址，如英国。）此地址通常由一个或多个部分组成。例如，地址“111 8th Avenue, New York, NY”包含四个地址组成部分，即“111”（街道门牌号）、“8th Avenue”（街道地址）、“New York”（城市）和“NY”（美国的一个州）。这些地址组成部分还包含其他信息，如下所述。 -
address_components[]是一个数组，其中包含相互独立的地址组成部分（如上文所述）。每个address_component通常包含以下几个组成部分：-
types[]是一个数组，用于表示返回结果的类型。 -
long_name，即地理编码器返回的完整文本说明或地址组成部分的名称。 -
short_name，即地址组成部分的缩写文本名称（如果有的话）。例如，阿拉斯加州的地址组成部分可能具有long_name“Alaska”和short_name“AK”（使用 2 个字母的邮政缩写）。
请注意，
address_components[]包含的地址组成部分的数量可能多于formatted_address中所注明的。 -
-
geometry包含以下信息：-
location，其中包含经过地理编码的纬度值和经度值。对于常规地址查询，此字段通常是最重要的。 -
location_type，其中存储了关于指定位置的附加数据。目前，系统支持以下值：-
"ROOFTOP"，用于表示返回的结果是一个精确的地理编码结果，因此我们可获得关于该地址的精确位置信息（可看到街道地址）。 -
"RANGE_INTERPOLATED"，用于表示返回的结果是一个近似值（通常为道路上的地址），该地址处于两个精确点（如十字路口）之间。当无法对街道地址进行精确的地理编码时，通常就会返回近似结果。 -
"GEOMETRIC_CENTER"，用于表示返回的结果是折线（如街道）或多边形（区域）等内容的几何中心。 -
"APPROXIMATE"，用于表示返回的结果是近似值。
-
-
viewport，其中包含用于显示所返回结果的推荐视口，并已指定为两个纬度/经度值以分别定义视口边框的southwest和northeast角。通常，该视口会用作向用户显示的结果的框架。 -
bounds（可选的返回项），其中存储了可完全包含所返回结果的边框。请注意，这些边界可能与建议的视口不匹配。（例如，旧金山包含法拉隆群岛，该岛实际上是旧金山市的一部分，但可能不应该在视口内返回。）
-
-
partial_match，用于表示地理编码器返回的结果无法与原始请求完全匹配，而仅与所请求的地址部分匹配。您应检查原始请求的拼写是否正确和/或地址是否完整。如果街道地址不属于请求中所传递的地区，往往会出现部分匹配。
由于我们无法保证针对 Geocoding API 请求的各个响应的确切格式，因此请勿假定元素位于绝对位置。（尤其是，Geocoding API 请求中的 address_components 的数量会根据所请求的地址而变化，并会随时间改变。）相反，您应当对响应进行解析，并通过表达式选择合适的值。有关详情，请参阅解析网络服务响应。
地址组成部分的类型
返回结果中的 types[] 数组用于表示地址类型。address_components[] 数组中也可能会返回这些类型，以表示特定地址组成部分的类型。地理编码器中的地址可能有多种类型；这些类型也可以视为“标记”。例如，许多城市都带有 political 和 locality 类型的标记。
HTTP 地理编码器支持并会返回以下类型：
-
street_address，用于表示一个精确的街道地址。 -
route，用于表示一条已命名的路线（例如“US 101”）。 -
intersection，用于表示一个大型十字路口（通常由两条主道交叉形成）。 -
political，用于表示一个政治实体（通常为一个代表行政管理区的多边形）。 -
country，用于表示政治实体，且通常列在地理编码器所返回结果的最前面。 -
administrative_area_level_1，用于表示仅次于国家/地区级别的行政实体。在美国，这类行政实体是指州。并非所有国家/地区都有该行政级别。 -
administrative_area_level_2，用于表示国家/地区级别下的二级行政实体。在美国，这类行政实体是指县。并非所有国家/地区都有该行政级别。 -
administrative_area_level_3，用于表示国家/地区级别下的三级行政实体。此类型表示较小的行政单位。并非所有国家/地区都有该行政级别。 -
colloquial_area，用于表示实体的通用别名。 -
locality，用于表示合并的市镇级别政治实体。 -
sublocality，用于表示仅次于地区级别的行政实体 -
neighborhood，用于表示已命名的邻近地区 -
premise，用于表示已命名的位置（通常为具有常用名称的建筑物或建筑群） -
subpremise，用于表示仅次于已命名位置级别的实体（通常为使用常用名称的建筑群中的某座建筑物） -
postal_code，用于表示邮政编码，以确定相应国家/地区内的邮寄地址。 -
natural_feature，用于表示著名的自然景观。 -
airport，用于表示机场。 -
park，用于表示已命名的公园。 -
point_of_interest，用于表示已命名的兴趣点。通常，这些“POI”是一些不易归入其他类别的比较有名的当地实体，如“帝国大厦”或“自由女神像”。
除此之外，地址组成部分还可以使用以下类型：
-
post_box，用于表示特定邮筒。 -
street_number，用于表示准确的街道编号。 -
floor，用于表示建筑物地址的楼层号。 -
room，用于表示建筑物地址的房间编号。
反向地理编码（地址查询）
“地理编码”这一术语通常指将易于理解的地址转换成地图上的一个点的过程。与此相反，将地图上的位置转换成易于理解的地址这一过程则称为“反向地理编码”。
Geocoding API 支持直接使用 latlng 参数进行反向地理编码。例如，以下查询包含了布鲁克林某一位置的纬度/经度值：
http://maps.googleapis.com/maps/api/geocode/json?latlng=40.714224,-73.961452&sensor=true_or_false
注意：在传入 latlng 参数时，请确保纬度值与经度值之间没有空格。
该查询返回了以下结果：
{
"status": "OK",
"results": [ {
"types": street_address,
"formatted_address": "275-291 Bedford Ave, Brooklyn, NY 11211, USA",
"address_components": [ {
"long_name": "275-291",
"short_name": "275-291",
"types": street_number
}, {
"long_name": "Bedford Ave",
"short_name": "Bedford Ave",
"types": route
}, {
"long_name": "New York",
"short_name": "New York",
"types": [ "locality", "political" ]
}, {
"long_name": "Brooklyn",
"short_name": "Brooklyn",
"types": [ "administrative_area_level_3", "political" ]
}, {
"long_name": "Kings",
"short_name": "Kings",
"types": [ "administrative_area_level_2", "political" ]
}, {
"long_name": "New York",
"short_name": "NY",
"types": [ "administrative_area_level_1", "political" ]
}, {
"long_name": "United States",
"short_name": "US",
"types": [ "country", "political" ]
}, {
"long_name": "11211",
"short_name": "11211",
"types": postal_code
} ],
"geometry": {
"location": {
"lat": 40.7142298,
"lng": -73.9614669
},
"location_type": "RANGE_INTERPOLATED",
"viewport": {
"southwest": {
"lat": 40.7110822,
"lng": -73.9646145
},
"northeast": {
"lat": 40.7173774,
"lng": -73.9583193
}
}
}
},
... Additional results[] ...
请注意，反向地理编码器返回了多个结果。这些结果的 "formatted_addresses" 不仅是指邮政地址，还包含了对位置进行地理命名的所有方式。例如，当对芝加哥市中的一个点进行地理编码时，地理编码的点可标注为其街道地址、城市（芝加哥）、州（伊利诺斯）或国家/地区（美国）。这些对地理编码器来说都是“地址”。反向地理编码器可将任何这些类型的地址作为有效结果返回。
反向地理编码器会匹配政治实体（国家/地区、州/省/自治区/直辖市、市和邻近地区）、街道地址和邮政编码。
前一查询所返回的 formatted_address 值的完整列表如下所示。
"formatted_address": "275-291 Bedford Ave, Brooklyn, NY 11211, USA", "formatted_address": "Williamsburg, NY, USA", "formatted_address": "New York 11211, USA", "formatted_address": "Kings, New York, USA", "formatted_address": "Brooklyn, NY, USA", "formatted_address": "New York, NY, USA", "formatted_address": "New York, USA", "formatted_address": "United States"
通常，地址将按照具体程度由高到低的顺序返回；最确切的地址将作为最显著的结果，本例就是如此。请注意，我们会返回各种不同的地址，从最具体的街道地址到较为笼统的政治实体（例如邻近地区、市、县、州/省/自治区/直辖市等）。如果您希望匹配更广泛的地址，可以检查返回的 Placemark 的 "types" 字段（请参阅上面的地址组成部分类型）。
注意：反向地理编码给出的是估计结果。地理编码器会试图在一定的偏差范围内查找最接近的可寻址位置；如果找不到匹配项，地理编码器通常不会返回结果。
视口偏向
您还可以指示地理编码服务优先显示指定视口（表示为边框）内的结果。要实现此目的，请在请求网址中设置 bounds 参数。请注意，偏向仅会优先显示边框内的结果；如果边框外的结果的相关程度更高，则您也可在边框内加入这些结果。
bounds 参数用于定义此边框的西南角和东北角的纬度/经度坐标（以竖线字符 (|) 分隔）。
例如，针对“温内特卡”的地理编码通常会返回芝加哥近郊地区的地址，具体如下：
请求：
http://maps.googleapis.com/maps/api/geocode/json?address=Winnetka&sensor=false
响应：
{ "status": "OK", "results": [ { "types": [ "locality", "political" ], "formatted_address": "Winnetka, IL, USA", "address_components": [ { "long_name": "Winnetka", "short_name": "Winnetka", "types": [ "locality", "political" ] }, { "long_name": "Illinois", "short_name": "IL", "types": [ "administrative_area_level_1", "political" ] }, { "long_name": "United States", "short_name": "US", "types": [ "country", "political" ] } ], "geometry": { "location": { "lat": 42.1083080, "lng": -87.7417070 }, "location_type": "APPROXIMATE", "viewport": { "southwest": { "lat": 42.0917501, "lng": -87.7737218 }, "northeast": { "lat": 42.1248616, "lng": -87.7096922 } }, "bounds": { "southwest": { "lat": 42.0885320, "lng": -87.7715480 }, "northeast": { "lat": 42.1284090, "lng": -87.7110160 } } } } ] }
不过，如果添加了 bounds 参数来定义一个洛杉矶圣费尔南多谷的边框，那么地理编码会返回该位置范围内邻近地区（名为“温内特卡”）的地址：
请求：
http://maps.googleapis.com/maps/api/geocode/json?address=Winnetka&bounds=34.172684,-118.604794|34.236144,-118.500938&sensor=false
响应：
{
"status": "OK",
"results": [ {
"types": [ "sublocality", "political" ],
"formatted_address": "Winnetka, California, USA",
"address_components": [ {
"long_name": "Winnetka",
"short_name": "Winnetka",
"types": [ "sublocality", "political" ]
}, {
"long_name": "Los Angeles",
"short_name": "Los Angeles",
"types": [ "administrative_area_level_3", "political" ]
}, {
"long_name": "Los Angeles",
"short_name": "Los Angeles",
"types": [ "administrative_area_level_2", "political" ]
}, {
"long_name": "California",
"short_name": "CA",
"types": [ "administrative_area_level_1", "political" ]
}, {
"long_name": "United States",
"short_name": "US",
"types": [ "country", "political" ]
} ],
"geometry": {
"location": {
"lat": 34.2131710,
"lng": -118.5710220
},
"location_type": "APPROXIMATE",
"viewport": {
"southwest": {
"lat": 34.1947148,
"lng": -118.6030368
},
"northeast": {
"lat": 34.2316232,
"lng": -118.5390072
}
},
"bounds": {
"southwest": {
"lat": 34.1791050,
"lng": -118.5883200
},
"northeast": {
"lat": 34.2353090,
"lng": -118.5534191
}
}
}
} ]
}
区域偏向
Google Geocoding API 所返回的地址结果会受到发送请求的区域（通常是国家/地区）的影响。例如，如果分别从美国境内的某个区域和西班牙搜索“旧金山”，则所得到的结果会有所不同。
您可以使用 region 参数，将 Geocoding API 设置为返回偏向特定区域的结果。该参数采用了指定区域偏向的 ccTLD（国家/地区代码顶级域）参数。大多数 ccTLD 代码都与 ISO 3166-1 代码相同，但也有一些需要注意的例外情况。例如，英国的 ccTLD 为“uk”(.co.uk)，而其 ISO 3166-1 代码为“gb”（特指“大不列颠及北爱尔兰联合王国”实体）。
正式启动了主 Google Maps 应用的每个区域都可以对地理编码结果进行偏向。请注意，偏向仅优先显示特定区域的结果，如果该区域外的结果的相关程度更高，您也可将其包含在内。
例如，由于 Geocoding API 的默认区域设为美国，因此，针对“托莱多”的地理编码返回了以下结果：
http://maps.googleapis.com/maps/api/geocode/json?address=Toledo&sensor=false
# Returns:
#
{
"status": "OK",
"results": [ {
"types": [ "locality", "political" ],
"formatted_address": "Toledo, OH, USA",
"address_components": [ {
"long_name": "Toledo",
"short_name": "Toledo",
"types": [ "locality", "political" ]
}, {
"long_name": "Ohio",
"short_name": "OH",
"types": [ "administrative_area_level_1", "political" ]
}, {
"long_name": "United States",
"short_name": "US",
"types": [ "country", "political" ]
} ],
"geometry": {
"location": {
"lat": 41.6529200,
"lng": -83.5777820
},
"location_type": "APPROXIMATE",
"viewport": {
"southwest": {
"lat": 41.5861889,
"lng": -83.7058414
},
"northeast": {
"lat": 41.7195821,
"lng": -83.4497226
}
},
"bounds": {
"southwest": {
"lat": 41.5803170,
"lng": -83.6947540
},
"northeast": {
"lat": 41.7326310,
"lng": -83.4545660
}
}
}
} ]
}
而在将区域设为 region=es（西班牙）的情况下，对“托莱多”的地理编码将会返回西班牙的城市：
http://maps.googleapis.com/maps/api/geocode/json?address=Toledo&sensor=false®ion=es
#
# Returns
#
{
"status": "OK",
"results": [ {
"types": [ "locality", "political" ],
"formatted_address": "Toledo, España",
"address_components": [ {
"long_name": "Toledo",
"short_name": "Toledo",
"types": [ "locality", "political" ]
}, {
"long_name": "Toledo",
"short_name": "TO",
"types": [ "administrative_area_level_2", "political" ]
}, {
"long_name": "Castilla-La Mancha",
"short_name": "CM",
"types": [ "administrative_area_level_1", "political" ]
}, {
"long_name": "España",
"short_name": "ES",
"types": [ "country", "political" ]
} ],
"geometry": {
"location": {
"lat": 39.8567775,
"lng": -4.0244759
},
"location_type": "APPROXIMATE",
"viewport": {
"southwest": {
"lat": 39.7882200,
"lng": -4.1525353
},
"northeast": {
"lat": 39.9252666,
"lng": -3.8964165
}
},
"bounds": {
"southwest": {
"lat": 39.8105550,
"lng": -4.1796354
},
"northeast": {
"lat": 39.9250920,
"lng": -3.8147915
}
}
}
} ]
}
组成部分过滤
Google Geocoding API 可返回限定于特定地区的地址结果。该限制是使用 components 过滤器指定的。过滤器包含一系列以竖线 (|) 分隔的 component:value 对。只有与所有过滤器都匹配的结果才会返回。过滤器值支持与其他地理编码请求一样的拼写校正和部分匹配方法。如果地理编码结果与某个组成部分过滤器是部分匹配的，那么该结果会在响应中包含一个partial_match 字段。
可进行的过滤的 components 包括：
-
route，可匹配路线的长名称或短名称。 -
locality，可同时匹配locality和sublocality类型。 -
administrative_area，可匹配所有administrative_area级别。 -
postal_code，可匹配postal_code和postal_code_prefix。 -
country，可匹配国家/地区名称或双字母 ISO 3166-1 国家/地区代码。
通过 components=country:ES 对“圣克鲁斯”进行地理编码会返回西班牙加那利群岛的圣克鲁斯德特内里费：
http://maps.google.com/maps/api/geocode/json?address=santa+cruz&components=country:ES&sensor=false
#
# Returns
#
{
"results" : [
{
"address_components" : [
{
"long_name" : "Santa Cruz de Tenerife",
"short_name" : "Santa Cruz de Tenerife",
"types" : [ "locality", "political" ]
},
{
"long_name" : "Santa Cruz de Tenerife",
"short_name" : "TF",
"types" : [ "administrative_area_level_2", "political" ]
},
{
"long_name" : "Canarias",
"short_name" : "CN",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "Spain",
"short_name" : "ES",
"types" : [ "country", "political" ]
}
],
"formatted_address" : "Santa Cruz de Tenerife, Spain",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 28.58939290,
"lng" : -16.11936290
},
"southwest" : {
"lat" : 28.40976910,
"lng" : -16.34359460
}
},
"location" : {
"lat" : 28.469810,
"lng" : -16.25485580
},
"location_type" : "APPROXIMATE",
"viewport" : {
"northeast" : {
"lat" : 28.58939290,
"lng" : -16.11936290
},
"southwest" : {
"lat" : 28.40976910,
"lng" : -16.34359460
}
}
},
"types" : [ "locality", "political" ]
}
],
"status" : "OK"
}
包含组成部分过滤器的查询只会返回与过滤器匹配的地理编码结果。如果找不到任何匹配项，地理编码器就会返回与过滤器本身匹配的结果。
http://maps.google.com/maps/api/geocode/json?address=Torun&components=administrative_area:TX|country:US&sensor=false
#
# Returns
#
{
"results" : [
{
"address_components" : [
{
"long_name" : "Texas",
"short_name" : "TX",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "United States",
"short_name" : "US",
"types" : [ "country", "political" ]
}
],
"formatted_address" : "Texas, USA",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 36.5007040,
"lng" : -93.50803900000001
},
"southwest" : {
"lat" : 25.83716390,
"lng" : -106.6456460
}
},
"location" : {
"lat" : 31.96859880,
"lng" : -99.90181310
},
"location_type" : "APPROXIMATE",
"viewport" : {
"northeast" : {
"lat" : 36.68395670,
"lng" : -91.70601210
},
"southwest" : {
"lat" : 26.99809190,
"lng" : -108.09761410
}
}
},
"types" : [ "administrative_area_level_1", "political" ]
}
],
"status" : "OK"
}
如果您提供的过滤器是彼此相互执行的，那么组成部分过滤会返回 ZERO_RESULTS 响应。
http://maps.google.com/maps/api/geocode/json?components=administrative_area:TX|country:FR&sensor=false
#
# Returns
#
{
"results" : [],
"status" : "ZERO_RESULTS"
}
使用 components 过滤器：您可以发起没有地址参数的查询，但是不能指定没有值的组成部分。
http://maps.google.com/maps/api/geocode/json?components=route:Annegatan|administrative_area:Helsinki|country:Finland&sensor=false
#
# Returns
#
{
"results" : [
{
"address_components" : [
{
"long_name" : "Annegatan",
"short_name" : "Annegatan",
"types" : [ "route" ]
},
{
"long_name" : "Helsinki",
"short_name" : "Helsinki",
"types" : [ "administrative_area_level_3", "political" ]
},
{
"long_name" : "Finland",
"short_name" : "FI",
"types" : [ "country", "political" ]
}
],
"formatted_address" : "Annegatan, Helsinki, Finland",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 60.17088090,
"lng" : 24.94279590
},
"southwest" : {
"lat" : 60.16266270,
"lng" : 24.93114440
}
},
"location" : {
"lat" : 60.16693210,
"lng" : 24.93683020
},
"location_type" : "GEOMETRIC_CENTER",
"viewport" : {
"northeast" : {
"lat" : 60.17088090,
"lng" : 24.94279590
},
"southwest" : {
"lat" : 60.16266270,
"lng" : 24.93114440
}
}
},
"types" : [ "route" ]
}
],
"status" : "OK"
}