谷歌提供的地理位置信息和反地理位置信息

源地址：https://developers.google.com/maps/documentation/geocoding/?hl=zh-CN#JSON

经在ios上开发测试，可行，但有时苹果定位得到的经纬度精度问题导致道路上稍微有些偏差，偏差不是特别的大

什么是地理编码

地理编码是将地址（如“1600 Amphitheatre Parkway, Mountain View, CA”）转换为地理坐标（如纬度 37.423021 和经度 -122.083739）的过程，您可以根据该地理坐标放置标记或定位地图。Google Geocoding API 可让您通过 HTTP 请求直接访问地理编码器。此外，该服务还可让您执行反向操作（将坐标转换为地址）；此过程称为“反向地理编码”。

受众

本文适用于要在某个 Google Maps API 所提供的地图中使用地理编码数据的网站和移动产品开发者。其中包含此 API 的使用说明以及有关可用参数的参考资料。

此服务通常用于对静态（事先已知的）地址进行地理编码，以便将应用内容放置在地图上；此服务并不用于实时响应用户输入等操作。对于动态地理编码（例如在用户界面元素内），请参阅关于 JavaScript API V2 客户端地理编码器、JavaScript API V3 客户端地理编码器或Maps API for Flash 客户端地理编码器的文档。

地理编码是一项既耗时又耗资源的任务。请尽可能地对已知地址预先进行地理编码（使用本文所述的 Geocoding API 或其他地理编码服务），并将结果存储在您自己设计的临时缓存中。

使用限制

使用 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 如下所示：

<GeocodeResponse> <status>OK</status> <result> <type>street_address</type> <formatted_address>1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA</formatted_address> <address_component> <long_name>1600</long_name> <short_name>1600</short_name> <type>street_number</type> </address_component> <address_component> <long_name>Amphitheatre Pkwy</long_name> <short_name>Amphitheatre Pkwy</short_name> <type>route</type> </address_component> <address_component> <long_name>Mountain View</long_name> <short_name>Mountain View</short_name> <type>locality</type> <type>political</type> </address_component> <address_component> <long_name>San Jose</long_name> <short_name>San Jose</short_name> <type>administrative_area_level_3</type> <type>political</type> </address_component> <address_component> <long_name>Santa Clara</long_name> <short_name>Santa Clara</short_name> <type>administrative_area_level_2</type> <type>political</type> </address_component> <address_component> <long_name>California</long_name> <short_name>CA</short_name> <type>administrative_area_level_1</type> <type>political</type> </address_component> <address_component> <long_name>United States</long_name> <short_name>US</short_name> <type>country</type> <type>political</type> </address_component> <address_component> <long_name>94043</long_name> <short_name>94043</short_name> <type>postal_code</type> </address_component> <geometry> <location> <lat>37.4217550</lat> <lng>-122.0846330</lng> </location> <location_type>ROOFTOP</location_type> <viewport> <southwest> <lat>37.4188514</lat> <lng>-122.0874526</lng> </southwest> <northeast> <lat>37.4251466</lat> <lng>-122.0811574</lng> </northeast> </viewport> </geometry> </result>
</GeocodeResponse>

请注意，该 XML 响应包括一个 <GeocodeResponse> 和以下两个顶级元素：

<status>，其中包含请求中的元数据。请参阅下面的状态代码。
<result> 元素（不包括或包括多个），每个该元素均包含一组经过地理编码的地址信息和几何图形信息。

请注意，此响应所花费的时间远远多于 JSON 响应。因此，除非您的服务出于某些原因需要 json，否则建议您将 xml 用作首选的输出标记。此外，请谨慎处理 XML 树，以便引用正确的节点和元素。有关用于输出处理的一些建议设计模式，请参阅使用 XPath 解析 XML。

本文档的其余部分将会使用 JSON 语法。在大多数情况下，对于说明本文档中的概念或字段名称，输出格式并不是很重要。不过，请注意以下细微差别：

XML 结果会包含在一个根 <GeocodeResponse> 元素中。
JSON 通过复数形式的数组 (types) 来表示多个元素的条目，而 XML 则使用多个单数形式的元素 (<type>) 表示这些条目。
空白元素会在 JSON 中通过空数组来表示，而在 XML 中则表示为没有此类元素。例如，未生成任何结果的响应将会在 JSON 中返回一个空的 results 数组，而在 XML 中则表示为没有 <result> 元素。

状态代码

地理编码响应对象中的 "status" 字段包含了请求的状态，并且可能会包含调试信息，以帮助您找到地理编码服务未正常工作的原因。"status" 字段可能包含以下值：

"OK"，用于表示未发生错误；已成功进行了地理编码且至少返回了一个地理编码结果。
"ZERO_RESULTS"，用于表示地理编码成功，但未返回任何结果。如果地理编码过程中传递的偏远位置 address 或 latlng 并不存在，就会出现这种情况。
"OVER_QUERY_LIMIT"，用于表示您超出了自己的配额。
"REQUEST_DENIED"，用于表示您的请求遭拒，这通常是由于缺少 sensor 参数。
"INVALID_REQUEST"，通常用于表示缺少查询内容（address 或 latlng）。

结果

当地理编码器返回结果时，会将其放在一个 (JSON) results 数组中。即使未返回任何结果（例如，如果地址不存在），地理编码器仍然会返回一个空的 results 数组。（XML 响应不包含或包含多个 <result> 元素。）

一个典型的结果由以下字段组成：

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 } } } }, ...Additionalresults[]...

请注意，反向地理编码器返回了多个结果。这些结果的 "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&region=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"