请求
Geocoding API 请求的格式如下：
https://maps.googleapis.com/maps/api/geocode/outputFormat?parameters
其中，outputFormat 可以是以下值之一：
json（推荐）表示以 JavaScript 对象表示法 (JSON) 的形式输出；或xml表示以 XML 格式输出
必须提供 HTTPS。
有些参数是必需的，有些则是可选的。根据网址的标准
参数使用和号 (&) 字符分隔。
本页的其余部分将介绍地理编码和 反向地理编码，这是因为 每种请求类型都有不同的参数
地理编码（纬度/经度查询）参数
地理编码请求中的必需参数：
address- 街道地址或 Plus Code 进行地理编码。根据格式指定地址 。应避免其他地址元素，例如企业名称以及单元号、套房号或楼层。街道地址元素应以空格分隔 （此处显示为经过网址转义为%20）：address=24%20Sussex%20Drive%20Ottawa%20ON
按如下格式设置 Plus Codes（加号经网址转义为%2B，空格经网址转义为%20）：- 全局代码是包含 4 个字符的区号和至少包含 6 个字符的区域代码（849VCWC8+R9 为
849VCWC8%2BR9）。 - 复合代码是至少包含 6 个字符的本地代码，包含
确切位置（CWC8+R9 Mountain View, CA, USA 为
CWC8%2BR9%20Mountain%20View%20CA%20USA）。
--或--
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对组成，并会完全限制地理编码器中的结果。如需了解详情，请参阅下文的组成部分过滤。extra_computations- 使用此参数指定 响应中的以下附加功能： 要针对同一 API 请求启用上述多个功能，请添加extra_computations参数， 例如：extra_computations=ADDRESS_DESCRIPTORS&extra_computations=BUILDING_AND_ENTRANCES
响应
地理编码响应以网址请求中的 output 标志指示的格式返回，默认情况下以 JSON 格式返回。
在此示例中，Geocoding API 请求针对地址“1600 Amphitheatre Parkway, Mountain View, CA”查询的 json 响应。
此请求演示了如何使用 JSON output 标志：
https://maps.googleapis.com/maps/api/geocode/json?address=1600+Amphitheatre+Parkway,+Mountain+View,+CA&key=YOUR_API_KEY
此请求演示了如何使用 XML output 标志：
https://maps.googleapis.com/maps/api/geocode/xml?address=1600+Amphitheatre+Parkway,+Mountain+View,+CA&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"
]
},
{
"long_name": "1351",
"short_name": "1351",
"types": [
"postal_code_suffix"
]
}
],
"formatted_address": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
"geometry": {
"location": {
"lat": 37.4222804,
"lng": -122.0843428
},
"location_type": "ROOFTOP",
"viewport": {
"northeast": {
"lat": 37.4237349802915,
"lng": -122.083183169709
},
"southwest": {
"lat": 37.4210370197085,
"lng": -122.085881130292
}
}
},
"place_id": "ChIJRxcAvRO7j4AR6hm6tys8yA8",
"plus_code": {
"compound_code": "CWC8+W7 Mountain View, CA",
"global_code": "849VCWC8+W7"
},
"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 树时应小心谨慎，以便引用正确的节点和元素。请参阅
<ph type="x-smartling-placeholder"></ph>
使用 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> elements.)
典型的结果包含以下字段：
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[]是一个数组，表示一个邮政编码中包含的最多 100 个市行政区。仅当结果为邮政内容时，此字段才会显示 包含多个市行政区的代码。geometry包含以下信息：location包含经过地理编码的纬度和经度值。普通 通常这个字段最为重要。location_type会存储有关指定位置的其他数据。目前支持以下值："ROOFTOP"，表示返回的结果是 我们可以提供精确到街道地址的位置信息。"RANGE_INTERPOLATED"表示 返回的结果反映了 在两个精确点（如交叉路口）之间用插值法得出的近似值（通常为道路上的近似值）。 当街道的屋顶地理编码不可用时，通常会返回插值结果 地址。"GEOMETRIC_CENTER"表示返回的结果是多段线（例如街道）或多边形（例如区域）等结果的几何图形中心。"APPROXIMATE"表示返回的结果是大致位置。
viewport包含用于显示返回结果的推荐视口，指定为两个纬度、经度值，分别定义视口边框的southwest和northeast角。一般来说， 视口用于在向用户显示结果时对结果进行框架处理。bounds（可选返回）存储可完全包含返回结果的边框。请注意，这些边界可能与推荐的视口不一致。（例如，在旧金山， 法拉隆群岛 理论上是城市的一部分，但可能不应该在视口中返回。）
-
plus_code（请参阅 Open Location Code 和 Plus Codes）是经过编码的位置引用，衍生自纬度和经度坐标，表示面积不超过 1/8,000 度 x 1/8,000 度（在赤道处约为 14 米 x 14 米）的区域。Plus Code 可用于在没有地址的地点（例如建筑物未编号，或者街道未命名）取代街道地址。该 API 并不总是返回加号编码。当该服务返回 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 搭配使用的标识符。例如，您可以 在place_idPlaces API 请求以获取 本地商家的详细信息，例如电话号码、营业时间、用户 评价等。查看地点 ID 概览。
地址类型和地址组成部分类型
结果中的 types[] 数组表示地址类型。地址类型的示例包括街道地址、国家/地区或政治实体。在 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 参数用于定义纬度/经度坐标
该边界框的西南角和东北角之间
(|) 字符分隔坐标。
例如，“Washington”的地理编码通常会返回美国华盛顿州：
请求：
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（国家/地区代码顶级）
domain) 参数，用于指定地区偏向。大多数 ccTLD 代码都与
ISO 3166-1 代码，但也有一些值得注意的例外情况。例如，United
英国的 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"
}
“Toledo”的地理编码请求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"
}