请求
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。
此请求演示了如何使用 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[]数组表示返回结果的类型。此数组包含一组零个或多个标记，用于标识结果中返回的地图项类型。例如，“芝加哥”的地理编码会返回“市行政区”，表示“芝加哥”是一个城市；同时返回“政治”，表示它是一个政治实体。如果地址组成部分没有已知类型，那么组成部分可能包含空类型数组。该 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 Code）是经过编码的位置引用，衍生自纬度和经度坐标，表示面积：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（西班牙）的“Toledo”地理编码请求将返回西班牙城市。
请求：
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 地图一致，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"
}
使用 components=country:ES 对“Santa Cruz”市行政区的地理编码请求在西班牙加那利群岛返回圣克鲁斯 - 特内里费。
请求：
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"
}