请求
Geocoding API 请求采用以下形式：
https://maps.googleapis.com/maps/api/geocode/outputFormat?parameters
其中 outputFormat 可以是以下值之一：
json（推荐）表示以 JavaScript 对象表示法 (JSON) 的形式输出；或xml表示以 XML 格式输出
对于使用 API 密钥的请求，必须采用 HTTPS 协议。
有些参数是必需的，而有些则是可选的。根据网址的标准，参数使用和号 (&) 字符分隔。
本页面的其余部分分别介绍了地理编码和反向地理编码，因为每种请求类型使用不同的参数。
地理编码（纬度/经度查询）参数
地理编码请求中的必需参数：
address- 要进行地理编码的街道地址或 Plus Code。根据相关国家/地区的邮政服务所使用的地址格式指定地址。应避免使用其他地址元素，例如商家名称和单元号、套房号或楼层。街道地址元素应以空格分隔（此处显示为网址转义为%20）：address=24%20Sussex%20Drive%20Ottawa%20ON
按如下格式设置 Plus 代码（加号经网址转义为%2B，空格经网址转义为%20）：- 全局代码是包含 4 个字符的区号和至少包含 6 个字符的区域代码（849VCWC8+R9 为
849VCWC8%2BR9）。 - 混合代码是至少包含 6 个字符的区域代码，具有明确的位置信息（CWC8+R9 Mountain View, CA, USA 为
CWC8%2BR9%20Mountain%20View%20CA%20USA）。
--OR--
components- 元素用竖线 (|) 分隔的组成部分过滤条件。如果提供了address，则组成部分过滤条件也可以作为可选参数接受。 组成部分过滤器中的每个元素都包含一个component:value对，可完全限制地理编码器中的结果。如需了解详情，请参阅下文的组成部分过滤。- 全局代码是包含 4 个字符的区号和至少包含 6 个字符的区域代码（849VCWC8+R9 为
key- 您的应用的 API 密钥。此密钥可以标识您的应用，以便进行配额管理。了解如何获取密钥。
如需获得更多指导，请参阅常见问题解答。
地理编码请求中的可选参数：
bounds- 视口的边界框，可在其中进一步自定义调整地理编码结果。此参数只会影响但不会完全限制地理编码器中的结果。（如需了解详情，请参阅下文的视口自定义调整部分）。language- 返回结果时使用的语言。- 请参阅支持的语言列表。Google 会经常更新支持的语言，因此该列表可能并非详尽无遗。
- 如果未提供
language，地理编码器会尝试使用Accept-Language标头中指定的首选语言，或发出请求的网域的当地语言。 - 地理编码器会尽力提供用户和当地人都能够看懂的街道地址。为实现该目标，它会以本地语言返回街道地址，必要时将其音译为可由用户阅读的文字，同时遵循首选语言。所有其他地址均以首选语言返回。地址组成部分均以同一语言返回，该语言从第一个组成部分中选择。
- 如果某个名称没有首选语言的版本，地理编码器会使用最接近的匹配项。
- 首选语言对 API 选择返回的结果集以及这些结果的返回顺序影响较小。地理编码器会根据语言对缩写进行不同的解读，例如街道类型的缩写，或者同义词可能在一种语言中有效但在另一种语言中无效。例如，utca 和 tér 在匈牙利语中分别是街道和方形的同义词。
region- 地区代码，已指定为 ccTLD（“顶级域名”）双字符值。此参数只会影响但不会完全限制地理编码器中的结果。（如需了解详情，请参阅下文的地区自定义调整部分）。该参数还会影响根据适用法律得出的结果。components- 一种组成部分过滤条件，其元素以竖线 (|) 分隔。如果请求不包含address，则必需提供组成部分过滤条件。 组成部分过滤器中的每个元素都包含一个component:value对，可完全限制地理编码器中的结果。如需了解详情，请参阅下文的组成部分过滤。
响应
地理编码响应以网址请求中 output 标志指示的格式返回，或默认以 JSON 格式返回。
在此示例中，Geocoding API 针对地点 ID“ChIJeRpOeF67j4AR9ydy_PIzPuM”的查询请求 json 响应。此地点 ID 是位于 1600 Amphitheatre Parkway, Mountain View, CA 的建筑物。
此请求演示了如何使用 JSON output 标志：
https://maps.googleapis.com/maps/api/geocode/json?place_id=ChIJeRpOeF67j4AR9ydy_PIzPuM&key=YOUR_API_KEY
此请求演示了如何使用 XML output 标志：
https://maps.googleapis.com/maps/api/geocode/xml?place_id=ChIJeRpOeF67j4AR9ydy_PIzPuM&key=YOUR_API_KEY
请选择下面的标签页，查看示例 JSON 和 XML 响应。
JSON
{
"results": [
{
"address_components": [
{
"long_name": "1600",
"short_name": "1600",
"types": [
"street_number"
]
},
{
"long_name": "Amphitheatre Parkway",
"short_name": "Amphitheatre Pkwy",
"types": [
"route"
]
},
{
"long_name": "Mountain View",
"short_name": "Mountain View",
"types": [
"locality",
"political"
]
},
{
"long_name": "Santa Clara County",
"short_name": "Santa Clara County",
"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.4224428,
"lng": -122.0842467
},
"location_type": "ROOFTOP",
"viewport": {
"northeast": {
"lat": 37.4239627802915,
"lng": -122.0829089197085
},
"southwest": {
"lat": 37.4212648197085,
"lng": -122.0856068802915
}
}
},
"place_id": "ChIJeRpOeF67j4AR9ydy_PIzPuM",
"plus_code": {
"compound_code": "CWC8+X8 Mountain View, CA",
"global_code": "849VCWC8+X8"
},
"types": [
"street_address"
]
}
],
"status": "OK"
}
请注意，JSON 响应包含两个根元素：
"status"包含请求中的元数据。请参阅下面的状态代码。"results"包含一个经过地理编码的地址信息和几何图形信息的数组。
对于地址查询，地理编码器通常只会返回 "results" 数组中的一个条目；不过，当地址查询不明确时，地理编码器可能会返回多个结果。
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 Parkway</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>Santa Clara County</long_name>
<short_name>Santa Clara County</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.4224428</lat>
<lng>-122.0842467</lng>
</location>
<location_type>ROOFTOP</location_type>
<viewport>
<southwest>
<lat>37.4212648</lat>
<lng>-122.0856069</lng>
</southwest>
<northeast>
<lat>37.4239628</lat>
<lng>-122.0829089</lng>
</northeast>
</viewport>
</geometry>
<place_id>ChIJeRpOeF67j4AR9ydy_PIzPuM</place_id>
<plus_code>
<global_code>849VCWC8+X8</global_code>
<compound_code>CWC8+X8 Mountain View, CA</compound_code>
</plus_code>
</result>
</GeocodeResponse>
请注意，XML 响应包含一个 <GeocodeResponse> 和两个顶级元素：
<status>包含请求中的元数据。请参阅下面的状态代码。- 零个或多个
<result>元素，每个元素包含一组经过地理编码的地址信息和几何图形信息。
XML 响应比 JSON 响应长得多。因此，除非您的服务出于某种原因需要 xml，否则我们建议您使用 json 作为首选输出标志。此外，在处理 XML 树时要小心，确保引用正确的节点和元素。如需了解用于输出处理的一些建议设计模式，请参阅
使用 XPath 解析 XML。
- XML 结果封装在一个根
<GeocodeResponse>元素中。 - JSON 通过复数数组 (
types) 表示具有多个元素的条目，而 XML 使用多个单数元素 (<type>) 表示这些条目。 - 空白元素在 JSON 中通过空数组表示，但在 XML 中通过不存在此类元素来表示。例如，未生成任何结果的响应将在 JSON 中返回一个空的
results数组，而在 XML 中则表示为没有<result>元素。
状态代码
地理编码响应对象中的 "status" 字段包含请求的状态，并且可能包含调试信息，以帮助您找到地理编码无法正常工作的原因。"status" 字段可能包含以下值：
"OK"表示未出现任何错误；已成功解析地址，并且至少返回了一个地理编码。"ZERO_RESULTS"表示地理编码成功，但未返回任何结果。如果向地理编码器传递了不存在的address，就可能会发生这种情况。OVER_DAILY_LIMIT表示以下任意一项：- API 密钥缺失或无效。
- 您的帐号尚未启用结算功能。
- 超出了您设定的用量上限。
- 提供的付款方式不再有效（例如，信用卡已过期）。
请参阅 Google 地图常见问题解答，了解如何解决此问题。
"OVER_QUERY_LIMIT"表示您超出了配额。"REQUEST_DENIED"表示您的请求已遭拒。"INVALID_REQUEST"通常表示缺少查询参数（address、components或latlng）。"UNKNOWN_ERROR"表示因服务器错误而无法处理该请求。如果您重试一次，请求可能会成功。
错误消息
如果地理编码器返回除 OK 以外的状态代码，地理编码响应对象中可能会包含额外的 error_message 字段。此字段包含关于给定状态代码背后原因的更多详细信息。
成果
当地理编码器返回结果时，会将这些结果放在一个 (JSON) results 数组中。即使地理编码器没有返回任何结果（例如地址不存在），它仍然会返回一个空的 results 数组。（XML 响应包含零个或多个 <result> 元素。）
典型的结果包含以下字段：
types[]数组表示返回结果的类型。此数组包含零个或多个标记，用于标识结果中所返回的地图项的类型。例如，“Chicago”的地理编码会返回“locality”，表示“Chicago”是一个城市；同时返回“political”，表示它是一个政治实体。如果地址组成部分没有已知的类型，组成部分可能具有空的类型数组。API 可能会根据需要添加新的类型值。有关详情，请参阅地址类型和地址组成部分。formatted_address是一个字符串，其中包含此位置直观易懂的地址。此地址通常相当于邮政地址。请注意，由于许可限制，某些国家/地区（例如英国）不允许发布真实的邮政地址。
设置了格式的地址在逻辑上包含一个或多个地址组成部分。例如，地址“111 8th Avenue, New York, NY”包含以下组成部分：“111”（门牌号）、“8th Avenue”（道路名称）、“New York”（城市）和“NY”（美国州名）。
请勿以程序化方式解析设有格式的地址。您应改用单独的地址组成部分，API 响应除了包含设有格式的地址字段外，还包含这些组成部分。
address_components[]是一个数组，其中包含适用于该地址的各个组成部分。每个地址组成部分通常包含以下字段：
types[]是一个数组，表示地址组成部分的类型。请参阅支持的类型列表。long_name是地理编码器返回的地址组成部分的完整文本说明或名称。short_name是地址组成部分的缩写文本名称（如果有）。例如，阿拉斯加州的地址组成部分可能包含long_name“Alaska”和short_name“AK”（使用 2 个字母的邮编缩写）。
address_components[]数组的注意事项如下：- 地址组成部分的数组包含的组成部分可能多于
formatted_address。 - 除了
formatted_address中包含的政治实体之外，数组不一定会纳入包含地址的所有政治实体。若要检索包含特定地址的所有政治实体，您应使用反向地理编码，并将地址的纬度/经度作为参数传递给请求。 - 两次请求之间的响应格式不一定相同。特别是，
address_components的数量因所请求的地址而异，对于同一个地址，数量也可能会随着时间推移而发生变化。组成部分在数组中的位置可能发生变化。组成部分的类型也可能发生变化。后续响应中可能缺少特定组成部分。
如需处理组成部分的数组，您应解析响应并通过表达式选择合适的值。请参阅有关 解析响应的指南。
postcode_localities[]是一个数组，表示邮政编码中包含的所有市行政区。仅当结果是包含多个市行政区的邮政编码时才会出现。geometry包含以下信息：location包含经过地理编码的纬度和经度值。对于普通的地址查询，此字段通常是最重要的。location_type会存储有关指定位置的其他数据。目前支持以下值："ROOFTOP"表示返回的结果是一个精确的地理编码，我们可获得精确到街道地址的位置信息。"RANGE_INTERPOLATED"表示返回的结果反映了两个精确点（例如交叉路口）之间用插值法得出的近似值（通常为道路上）。当某个街道地址的屋顶地理编码不可用时，通常会返回插值结果。"GEOMETRIC_CENTER"表示返回的结果是多段线（例如街道）或多边形（例如区域）等结果的几何中心。"APPROXIMATE"表示返回的结果是近似值。
viewport包含用于显示返回结果的推荐视口，并指定为两个纬度/经度值，分别定义视口边界框的southwest和northeast角。通常，视口用于在向用户显示结果时作为结果的框架。bounds（选择性返回）存储可完全包含返回结果的边界框。请注意，这些边界可能与推荐的视口不一致。（例如，旧金山包含法拉隆岛，理论上后者是旧金山的一部分，但可能不应该在视口中返回）。
-
plus_code（请参阅开放位置代码和 Plus Codes）是一个基于纬度和经度坐标的编码位置引用，表示的区域为：1/8000 度乘以 1/8000 度（赤道约 14 米 x 14 米）或更小的区域。Plus Codes 可用于在没有地址的地方（例如建筑物未编号，或者街道未命名）取代街道地址。API 并不总是会返回 Plus 代码。如果服务返回 Plus 代码，系统会将其格式设置为全局代码和混合代码：
global_code是包含 4 个字符的区号和至少包含 6 个字符的区域代码 (849VCWC8+R9)。compound_code是至少包含 6 个字符的区域代码，具有明确的位置信息（CWC8+R9, Mountain View, CA, USA）。请勿以程序化方式解析此内容。
-
partial_match表示地理编码器无法返回与原始请求完全匹配的结果，尽管它能够匹配所请求地址的一部分内容。建议您检查一下原始请求中是否存在拼写错误和/或地址不完整的情况。部分匹配的最常见原因是请求中所传递的市行政区内不存在相关街道地址。当请求与同一市行政区中的两个或更多位置相匹配时，也可能会返回部分匹配。例如，无论是 Henry Street 还是 Henrietta Street，“Hillpar St, Bristol, UK”都会返回部分匹配。请注意，如果请求中包含拼写错误的地址组成部分，地理编码服务可能会推荐备选地址。通过这种方式触发的建议也将标记为部分匹配。
place_id是唯一标识符，可以与其他 Google API 搭配使用。例如，您可以在 Places API 请求中使用place_id来获取本地商家的详细信息，例如电话号码、营业时间、用户评价等。请参阅地点 ID 概览。
地址类型和地址组成部分类型
结果中的 types[] 数组表示地址类型。地址类型的示例包括街道地址、国家/地区或政治实体。address_components[] 中还有一个 types[] 数组，表示地址各个部分的类型。示例包括门牌号或国家/地区。（下面是类型的完整列表。）地址可能有多种类型。这些类型可能会被视为“标记”。
例如，许多城市都带有 political 和 locality 类型的标记。
地理编码器在地址类型和地址组成部分类型数组中支持并返回以下类型：
street_address表示精确的街道地址。route表示已命名的路线（例如“US 101”）。intersection表示主要交叉路口，通常是两条主要道路的交叉路口。political表示政治实体。这种类型通常表示某些行政管理区的多边形区域。country表示国家政治实体，通常列在地理编码器所返回结果的最前面。administrative_area_level_1表示国家/地区级别以下的一级行政实体。在美国，这类行政级别是指州。并不是所有国家都设有这类行政级别。在大多数情况下，administrative_area_level_1 简称可高度匹配 ISO 3166-2 行政区划以及其他广为传播的列表；不过，我们无法对此做出保证，因为我们的地理编码结果基于各种信号和位置数据。administrative_area_level_2表示国家/地区级别以下的二级行政实体。在美国，这类行政级别是指县。并不是所有国家都设有这类行政级别。administrative_area_level_3表示国家/地区级别以下的三级行政实体。此类型表示较小的行政区划单位。并不是所有国家都设有这类行政级别。administrative_area_level_4表示国家/地区级别以下的四级行政实体。此类型表示较小的行政区划单位。并不是所有国家都设有这类行政级别。administrative_area_level_5表示国家/地区级别以下的五级行政实体。此类型表示较小的行政区划单位。并不是所有国家都设有这类行政级别。administrative_area_level_6表示国家/地区级别以下的六级行政实体。此类型表示较小的行政区划单位。并不是所有国家都设有这类行政级别。administrative_area_level_7表示国家/地区级别以下的七级行政实体。此类型表示较小的行政区划单位。并不是所有国家都设有这类行政级别。colloquial_area表示实体的常用替代名称。locality表示合并的城市或城镇政治实体。sublocality表示市行政区以下的一级行政实体。对于某些位置，可能会收到以下任一类型：从sublocality_level_1到sublocality_level_5。每个子级市行政区级别都是一个行政实体。数字越大表示地理区域越小。neighborhood表示已命名的街区。premise表示已命名的位置，通常是具有常见名称的建筑或建筑群。subpremise表示已命名位置以下的一级实体，通常是具有共同名称的建筑群中的单个建筑物。plus_code表示经过编码的位置引用，衍生自纬度和经度。Plus Codes 可用于在没有街道地址的地点（例如建筑物未编号，或者街道未命名）取代街道地址。如需了解详情，请参阅 https://plus.codes。postal_code表示国家/地区内邮寄地址所用的邮政编码。natural_feature表示某个明显的自然地貌。airport表示机场。park表示已命名的公园。point_of_interest表示已命名的地图注点。通常情况下，这些“地图注点”是当地的著名实体，无法轻易归入其他类别，例如“帝国大厦”或“埃菲尔铁塔”。
空的类型列表表示特定地址组成部分没有对应的已知类型，例如法国的地点 (Lieu-dit)。
除了上述类型之外，地址组成部分还可能包括此处列出的类型。此列表并不详尽，并且可能会发生变化。
floor表示某个建筑物地址的楼层。establishment通常表示某个尚未归类的地点。landmark表示附近的地点，可用作辅助导航的参考。point_of_interest表示已命名的地图注点。parking表示停车场或停车楼。post_box表示特定的邮箱。postal_town表示地理区域分组（例如locality和sublocality），在某些国家/地区用于邮寄地址。room表示某个建筑物地址的房间。street_number表示精确的门牌号。bus_station、train_station和transit_station分别表示公交车、火车或公共交通车站的位置。
视口自定义调整
在地理编码请求中，您可以指示地理编码服务优先显示给定视口（表示为边界框）中的结果。为此，您可以在请求网址中设置 bounds 参数。
bounds 参数定义此边界框的西南角和东北角的纬度/经度坐标，并使用竖线 (|) 字符分隔坐标。
例如，“华盛顿州”的地理编码通常返回美国华盛顿州：
请求：
https://maps.googleapis.com/maps/api/geocode/json?address=Washington&key=YOUR_API_KEY
响应：
{
"results" : [
{
"address_components" : [
{
"long_name" : "Washington",
"short_name" : "WA",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "United States",
"short_name" : "US",
"types" : [ "country", "political" ]
}
],
"formatted_address" : "Washington, USA",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 49.0024442,
"lng" : -116.91558
},
"southwest" : {
"lat" : 45.543541,
"lng" : -124.8489739
}
},
"location" : {
"lat" : 47.7510741,
"lng" : -120.7401385
},
"location_type" : "APPROXIMATE",
"viewport" : {
"northeast" : {
"lat" : 49.0024442,
"lng" : -116.91558
},
"southwest" : {
"lat" : 45.543541,
"lng" : -124.8489739
}
}
},
"place_id" : "ChIJ-bDD5__lhVQRuvNfbGh4QpQ",
"types" : [ "administrative_area_level_1", "political" ]
}
],
"status" : "OK"
}
不过，如果添加 bounds 参数来定义美国东北部周围的边界框，则此地理编码会返回华盛顿特区的市：
请求：
https://maps.googleapis.com/maps/api/geocode/json?address=Washington&bounds=36.47,-84.72%7C43.39,-65.90&key=YOUR_API_KEY
响应：
{
"results" : [
{
"address_components" : [
{
"long_name" : "Washington",
"short_name" : "Washington",
"types" : [ "locality", "political" ]
},
{
"long_name" : "District of Columbia",
"short_name" : "District of Columbia",
"types" : [ "administrative_area_level_2", "political" ]
},
{
"long_name" : "District of Columbia",
"short_name" : "DC",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "United States",
"short_name" : "US",
"types" : [ "country", "political" ]
}
],
"formatted_address" : "Washington, DC, USA",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 38.9958641,
"lng" : -76.90939299999999
},
"southwest" : {
"lat" : 38.7916449,
"lng" : -77.119759
}
},
"location" : {
"lat" : 38.9071923,
"lng" : -77.03687069999999
},
"location_type" : "APPROXIMATE",
"viewport" : {
"northeast" : {
"lat" : 38.9958641,
"lng" : -76.90939299999999
},
"southwest" : {
"lat" : 38.7916449,
"lng" : -77.119759
}
}
},
"place_id" : "ChIJW-T2Wt7Gt4kRKl2I1CJFUsI",
"types" : [ "locality", "political" ]
}
],
"status" : "OK"
}
地区自定义调整
在地理编码请求中，您可以使用 region 参数指示地理编码服务返回偏向特定区域的结果。此参数采用指定地区偏向的 ccTLD（国家/地区代码顶级域名）参数。除了某些明显的例外情况，大多数 ccTLD 代码都与 ISO 3166-1 代码相同。例如，英国的 ccTLD 为“uk”(.co.uk)，而其 ISO 3166-1 代码为“gb”（特指“大不列颠及北爱尔兰联合王国”）。
对于正式发布了主要 Google 地图应用的每个网域，都可以对地理编码结果进行偏向。请注意，自定义调整只是优先显示特定网域的结果；如果在此网域以外存在更相关的结果，也可能会将这些结果包括在内。
例如，由于 Geocoding API 的默认网域设置为美国，因此“Toledo”的地理编码会返回以下结果。请求：
https://maps.googleapis.com/maps/api/geocode/json?address=Toledo&key=YOUR_API_KEY
响应：
{
"results" : [
{
"address_components" : [
{
"long_name" : "Toledo",
"short_name" : "Toledo",
"types" : [ "locality", "political" ]
},
{
"long_name" : "Lucas County",
"short_name" : "Lucas County",
"types" : [ "administrative_area_level_2", "political" ]
},
{
"long_name" : "Ohio",
"short_name" : "OH",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "United States",
"short_name" : "US",
"types" : [ "country", "political" ]
}
],
"formatted_address" : "Toledo, OH, USA",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 41.732844,
"lng" : -83.454229
},
"southwest" : {
"lat" : 41.580266,
"lng" : -83.69423700000002
}
},
"location" : {
"lat" : 41.6639383,
"lng" : -83.55521200000001
},
"location_type" : "APPROXIMATE",
"viewport" : {
"northeast" : {
"lat" : 41.732844,
"lng" : -83.454229
},
"southwest" : {
"lat" : 41.580266,
"lng" : -83.69423700000002
}
}
},
"place_id" : "ChIJeU4e_C2HO4gRRcM6RZ_IPHw",
"types" : [ "locality", "political" ]
}
],
"status" : "OK"
}
对包含 region=es（西班牙）的“托莱多”的地理编码请求将返回西班牙的城市。
请求：
https://maps.googleapis.com/maps/api/geocode/json?address=Toledo®ion=es&key=YOUR_API_KEY
响应：
{
"results" : [
{
"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" : "Castile-La Mancha",
"short_name" : "CM",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "Spain",
"short_name" : "ES",
"types" : [ "country", "political" ]
}
],
"formatted_address" : "Toledo, Spain",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 39.88605099999999,
"lng" : -3.9192423
},
"southwest" : {
"lat" : 39.8383676,
"lng" : -4.0796176
}
},
"location" : {
"lat" : 39.8628316,
"lng" : -4.027323099999999
},
"location_type" : "APPROXIMATE",
"viewport" : {
"northeast" : {
"lat" : 39.88605099999999,
"lng" : -3.9192423
},
"southwest" : {
"lat" : 39.8383676,
"lng" : -4.0796176
}
}
},
"place_id" : "ChIJ8f21C60Lag0R_q11auhbf8Y",
"types" : [ "locality", "political" ]
}
],
"status" : "OK"
}
组成部分过滤
在地理编码响应中，Geocoding API 可以返回仅限于特定区域的地址结果。您可以使用 components 过滤条件指定限制。过滤条件由用竖线 (|) 分隔的 component:value 对列表组成。过滤条件值支持与其他地理编码请求相同的拼写校正和部分匹配方法。如果地理编码器发现某个组成部分过滤条件的部分匹配项，响应中将包含一个 partial_match 字段。
可以过滤的 components 包括：
postal_code与postal_code和postal_code_prefix匹配。country用于匹配国家/地区名称或两个字母的 ISO 3166-1 国家/地区代码。该 API 按照 ISO 标准来定义国家/地区，因此，过滤时使用国家/地区对应的 ISO 代码，效果最好。
以下 components 可用于影响结果，但不会被强制执行：
route用于匹配路线的全称或简称。locality与locality和sublocality类型匹配。administrative_area匹配所有administrative_area级别。
关于组成部分过滤的注意事项：
- 请勿在请求中重复使用这些组成部分过滤条件，否则 API 会返回
Invalid_request：country、postal_code、route - 如果请求包含重复的组成部分过滤条件，则 API 将这些过滤条件评估为 AND，而不是 OR。
- 结果与 Google 地图一致，偶尔会产生意外的
ZERO_RESULTS响应。在某些用例中，使用地点自动补全功能可以带来更好的结果。如需了解详情，请参阅此常见问题解答。 - 对于每个地址组成部分，请在
address参数或components过滤器中指定相应地址组成部分，但不能同时在两者中指定。在这两个属性中指定相同的值可能会导致ZERO_RESULTS。
具有 components=country:GB 的“High St, Hastings”地理编码会返回英国黑斯廷斯的结果，而不是返回美国哈德逊的黑斯廷斯的结果。
请求：
https://maps.googleapis.com/maps/api/geocode/json?address=high+st+hasting&components=country:GB&key=YOUR_API_KEY
响应：
{
"results" : [
{
"address_components" : [
{
"long_name" : "High Street",
"short_name" : "High St",
"types" : [ "route" ]
},
{
"long_name" : "Hastings",
"short_name" : "Hastings",
"types" : [ "postal_town" ]
},
{
"long_name" : "East Sussex",
"short_name" : "East Sussex",
"types" : [ "administrative_area_level_2", "political" ]
},
{
"long_name" : "England",
"short_name" : "England",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "United Kingdom",
"short_name" : "GB",
"types" : [ "country", "political" ]
},
{
"long_name" : "TN34 3EY",
"short_name" : "TN34 3EY",
"types" : [ "postal_code" ]
}
],
"formatted_address" : "High St, Hastings TN34 3EY, UK",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 50.8601041,
"lng" : 0.5957329
},
"southwest" : {
"lat" : 50.8559061,
"lng" : 0.5906163
}
},
"location" : {
"lat" : 50.85830319999999,
"lng" : 0.5924594
},
"location_type" : "GEOMETRIC_CENTER",
"viewport" : {
"northeast" : {
"lat" : 50.8601041,
"lng" : 0.5957329
},
"southwest" : {
"lat" : 50.8559061,
"lng" : 0.5906163
}
}
},
"partial_match" : true,
"place_id" : "ChIJ-Ws929sa30cRKgsMNVkPyws",
"types" : [ "route" ]
}
],
"status" : "OK"
}
针对“Santa Cruz”（圣克鲁斯）市行政区的地理编码请求 components=country:ES，返回西班牙加那利群岛的圣克鲁斯 - 德特内里费。
请求：
https://maps.googleapis.com/maps/api/geocode/json?components=locality:santa+cruz|country:ES&key=YOUR_API_KEY
响应：
{
"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" : "Canary Islands",
"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.487616,
"lng" : -16.2356646
},
"southwest" : {
"lat" : 28.4280248,
"lng" : -16.3370045
}
},
"location" : {
"lat" : 28.4636296,
"lng" : -16.2518467
},
"location_type" : "APPROXIMATE",
"viewport" : {
"northeast" : {
"lat" : 28.487616,
"lng" : -16.2356646
},
"southwest" : {
"lat" : 28.4280248,
"lng" : -16.3370045
}
}
},
"place_id" : "ChIJcUElzOzMQQwRLuV30nMUEUM",
"types" : [ "locality", "political" ]
}
],
"status" : "OK"
}
仅当您提供相互排除的过滤器时，组成部分过滤才会返回 ZERO_RESULTS 响应。
请求：
https://maps.googleapis.com/maps/api/geocode/json?components=administrative_area:TX|country:FR&key=YOUR_API_KEY
响应：
{
"results" : [],
"status" : "ZERO_RESULTS"
}
您可以在不使用地址参数的情况下，使用 components 过滤条件进行有效查询。（在对完整地址进行地理编码时，如果请求包含建筑物的名称和数量，则需要使用 address 参数。）
请求：
https://maps.googleapis.com/maps/api/geocode/json?components=route:Annankatu|administrative_area:Helsinki|country:Finland&key=YOUR_API_KEY
响应：
{
"results" : [
{
"address_components" : [
{
"long_name" : "Annankatu",
"short_name" : "Annankatu",
"types" : [ "route" ]
},
{
"long_name" : "Helsinki",
"short_name" : "HKI",
"types" : [ "locality", "political" ]
},
{
"long_name" : "Finland",
"short_name" : "FI",
"types" : [ "country", "political" ]
},
{
"long_name" : "00101",
"short_name" : "00101",
"types" : [ "postal_code" ]
}
],
"formatted_address" : "Annankatu, 00101 Helsinki, Finland",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 60.168997,
"lng" : 24.9433353
},
"southwest" : {
"lat" : 60.16226160000001,
"lng" : 24.9332897
}
},
"location" : {
"lat" : 60.1657808,
"lng" : 24.938451
},
"location_type" : "GEOMETRIC_CENTER",
"viewport" : {
"northeast" : {
"lat" : 60.168997,
"lng" : 24.9433353
},
"southwest" : {
"lat" : 60.16226160000001,
"lng" : 24.9332897
}
}
},
"place_id" : "ChIJARW7C8sLkkYRgl4je4-RPUM",
"types" : [ "route" ]
}
],
"status" : "OK"
}