请求
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）。
--OR--
components- 包含元素的组成部分过滤条件 使用竖线 (|) 分隔。也可以使用组成部分过滤条件 作为可选参数（如果提供了address）。 组成部分过滤器中的每个元素都包含一个component:value对，并完全限制结果 。查看更多信息 组成部分过滤。- 全局代码是包含 4 个字符的区号，且长度至少为 6 个字符
本地代码（849VCWC8+R9 为
key- 您的应用的 API 密钥。此密钥用于标识 以便管理配额了解如何 获取密钥。
请参阅常见问题解答 。
地理编码请求中的可选参数：
bounds- 视口的边界框 用于更显著地偏向地理编码结果。这个参数 只会影响但不会完全限制地理编码器中的结果。（有关 请参阅下面的视口偏向）。language- 表示 返回结果。- 请参阅支持的 语言。Google 会经常更新支持的语言 列表可能并不详尽。
- 如果未提供
language，地理编码器会尝试 请使用Accept-Language标头或 发送请求的网域。 - 地理编码器会尽力提供符合以下要求的街道地址 便于用户和本地用户阅读为了实现这一目标， 以当地语言返回街道地址，并将其音译为 脚本供用户阅读，并遵守首选的 语言。所有其他地址都返回首选 语言。地址组成部分均以相同的语言返回， 也就是从第一个组件中选择的
- 如果某个名称没有以首选语言提供，地理编码器会使用 最接近的匹配项。
- 首选语言对要返回的结果集影响较小 API 选择返回的条目以及这些条目的返回顺序。 地理编码器会根据不同的语言对缩写进行不同的解读， 例如街道类型的缩写或 对一种语言有效，但在另一种语言中无效。例如 utca 和 tér 分别是 street 和 Square 的同义词 匈牙利语
region- 地区代码，已指定为 ccTLD （即“顶级域名”）双字符值。此参数只会 影响，而不是完全限制地理编码器中的结果。（有关 请参阅下面的地区自定义调整）。通过 参数也会影响适用法律所规定的结果。components- 包含元素的组成部分过滤条件 使用竖线 (|) 分隔。组成部分过滤条件为 如果请求不包含address，则此属性为必需属性。 组成部分过滤器中的每个元素都包含一个component:value对，并完全限制结果 。查看更多信息 组成部分过滤。extra_computations- 使用此参数指定 响应中的以下附加功能： 要针对同一 API 请求启用上述多个功能，请添加extra_computations参数， 例如：extra_computations=ADDRESS_DESCRIPTORS&extra_computations=BUILDING_AND_ENTRANCES
响应
地理编码响应以 output 标志指示的格式返回
或默认为 JSON 格式。
在此示例中，Geocoding API 请求一个 json
对“1600 Amphitheatre Parkway, Mountain View,
CA”。
此请求演示了如何使用 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 响应长。对于
因此，我们建议您将 json 作为首选
输出标志，除非您的服务出于某些原因需要 xml。
此外，处理 XML 树时要小心，
适当的节点和元素。请参阅
<ph type="x-smartling-placeholder"></ph>
使用 XPath 解析 XML，以获取用于输出处理的一些建议设计模式。
- XML 结果封装在根
<GeocodeResponse>元素中。 - JSON 通过复数数组 (
types) 表示包含多个元素的条目， 而 XML 使用多个单数元素 (<type>) 表示这些元素。 - 空白元素在 JSON 中通过空数组表示，而没有任何元素
XML 中的此类元素。未生成任何结果的响应将返回空
results数组（在 JSON 中），但在 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的数量因所请求的地址而异，对于同一个地址，数量也可能会随着时间推移而发生变化。组成部分在数组中的位置可能发生变化。组成部分的类型也可能发生变化。后续响应中可能缺少特定组成部分。
要处理组件数组，您应解析响应 并通过表达式选择合适的值。请参阅 <ph type="x-smartling-placeholder"></ph> 解析响应。
postcode_localities[]是一个数组，最多表示 100 个市行政区 包含邮政编码。仅当结果为邮政内容时，此字段才会显示 包含多个市行政区的代码。geometry包含以下信息：location包含经过地理编码的纬度值和经度值。普通 通常这个字段最为重要。location_type存储有关指定位置的其他数据。通过 目前支持以下值："ROOFTOP"，表示返回的结果是 我们可以提供精确到街道地址的位置信息。"RANGE_INTERPOLATED"表示 返回的结果反映了 在两个精确点（如交叉路口）之间用插值法得出的近似值（通常为道路上的近似值）。 当街道的屋顶地理编码不可用时，通常会返回插值结果 地址。"GEOMETRIC_CENTER"表示 返回的结果是 如多段线（如街道）或多边形（区域）的结果。"APPROXIMATE"表示 返回的结果是近似值。
viewport包含建议用于显示的视口 返回的结果，指定为两个纬度/经度值，分别定义southwest和 视口边界框的northeast角。一般来说， 视口用于在向用户显示结果时对结果进行框架处理。bounds（可选返回）存储边界框 可完全包含返回的结果。请注意，这些边界可能与 建议视口（例如，在旧金山， 法拉隆群岛 理论上是城市的一部分，但可能不应该在视口中返回。）
-
plus_code（请参阅 打开位置代码 和 Plus Codes）是一种编码 通过纬度和经度坐标衍生的位置参考， 表示面积：1/8000 度 x 1/8000 度（约 14 米 x 赤道 14 米）或更小。Plus Codes 可以用于 没有地址的地点（没有建筑物的信息）中的街道地址 或街道未命名）。该 API 不一定会返回 Plus 代码。当服务返回 Plus 代码时，系统会将其格式设置为全局代码和复合代码：
global_code是 4 个字符的区号和至少 6 个字符的本地代码 (849VCWC8+R9)。compound_code是至少包含 6 个字符的区域代码，具有明确的位置信息 （CWC8+R9，山景城，加利福尼亚州）。请勿以程序化方式解析此内容。
-
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 参数用于定义纬度/经度坐标
该边界框的西南角和东北角之间
(|) 字符分隔坐标。
例如，“华盛顿”的地理编码通常会返回美国的 华盛顿：
请求：
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 地图应用正式发布。请注意，自定义调整仅 优先显示针对特定网域的结果；如果有更相关的结果 也可能包含在内。
例如，“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。
“High St, Hastings”的地理编码使用components=country:GB
返回英格兰黑斯廷斯（而非美国黑斯廷斯安哈德逊）的结果。
请求：
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"
}