一切就绪!

着手开发前,请先阅读我们的开发者文档

激活 Google Maps Geocoding API

为帮助您起步,我们将引导您在 Google Developers Console 中先完成几项任务:

  1. 创建或选择项目
  2. 激活 Google Maps Geocoding API
  3. 创建相应密钥
继续

开发人员指南

该服务还作为客户端 Google Maps JavaScript API 的一部分提供,或者在服务器端与 Java Client、Python Client、Go Client 以及 Node.js Client for Google Maps Services 配合使用。注:无论服务使用方式如何,均执行相同的每日使用限额。每日请求次数按客户端与服务器端查询次数之和计算。

什么是地理编码?

地理编码是将地址(如“1600 Amphitheatre Parkway, Mountain View, CA”)转换为地理坐标(如纬度 37.423021 和经度 -122.083739)的过程,您可以借此在地图上放置标记,或在地图上定位。

反向地理编码是将地理坐标转换为可人工读取的地址的过程。Google Maps Geocoding API 的反向地理编码服务还可让您找到对应于给定的地点 ID 的地址。

Google Maps Geocoding API 提供了一种通过 HTTP 请求来访问这些服务的直接方法。下例通过 Google Maps JavaScript API 使用 Geocoding 服务来展示基本功能。

全屏查看本示例可了解 Geocoding API 的其他功能,例如其他可用于定制请求的选项(组成部分过滤和视口偏向)以及有关每个结果的更多详情。

开始前的准备工作

本文介绍 Google Maps Geocoding API 网络服务。其适用对象是想要在其中一个 Google Maps API 提供的地图内使用地理编码数据的网站和移动开发者。

:此服务通常用于对(预先知道的)静态地址进行地理编码,以便将应用内容放置到地图上;此服务并非设计用于实时响应用户输入。如需了解有关动态地理编码(例如,在某个用户界面元素内)的信息,请查阅关于 Google Maps JavaScript API 客户端地理编码器和/或 Google Play 服务 Location API 的文档。

地理编码是一项时间和资源密集型任务。只要有可能,请(使用此处所描述的 Google Maps Geocoding API 或其他地理编码服务)对已知地址进行预地理编码,并将结果存储在您自己的设计的临时缓存中。

要使用 Google Maps Geocoding API,您需要一个 API 密钥。在开始使用 Geocoding API 进行开发前,请查看身份验证要求API 使用限额

Google Maps Geocoding API 请求格式

Google Maps Geocoding API 请求使用以下格式:

https://maps.googleapis.com/maps/api/geocode/outputFormat?parameters

其中 outputFormat 可以是以下值之一:

  • json(推荐),表示以 JavaScript 对象标记 (JSON) 格式输出;或
  • xml,表示以 XML 格式输出

如需通过 HTTP 访问 Google Maps Geocoding API,请使用:

http://maps.googleapis.com/maps/api/geocode/outputFormat?parameters

安全性很重要,建议尽可能使用 HTTPS,对于请求中包含用户位置等敏感用户数据的应用,更须如此。使用 HTTPS 加密可提高应用的安全性及其抵御窥探或篡改的能力。

:网址必须编码正确方有效,并且对于所有网络服务,均有 8192 字符数限制。请在构建网址时注意这一限制。请注意,不同的浏览器、代理和服务器可能同样具有不同的 URL 字符限制。

有些参数是必填的,而有些是可选的。依照 URL 的标准,参数都使用“与”字符 (&) 分隔。

因为每种请求类型使用的参数不同,所以本页面的其余部分分别介绍了地理编码反向地理编码

地理编码(纬度/经度查询)

地理编码请求中的必填参数:

  • address – 要进行地理编码的街道地址,采用相关国家/地区的全国邮政服务所使用的格式。应避免其他地址元素,例如企业名称以及单元号、套房号或楼层。请参阅常见问题解答以获得更多指导。
        
    components – 您希望获得其地理编码的组成部分过滤器。如需了解详细信息,请参阅组成部分过滤。如果提供了 address,还将接受组成部分过滤器作为可选参数。
  • key – 您的应用的 API 密钥。此密钥可以标识您的应用,以便进行配额管理。了解如何获取密钥

    注:Google Maps APIs Premium Plan 客户可以在 Geocoding 请求中使用 API 密钥或有效的客户端 ID 和数字签名。获取有关 Premium Plan 客户身份验证参数的更多信息。

地理编码请求中的可选参数:

  • bounds – 视口的边框,在其中可以使地理编码结果更显著地发生偏向。此参数只会影响,而不会完全限制地理编码器中的结果。(如需了解详细信息,请参阅下面的视口偏向。)
  • language – 返回结果时使用的语言。
    • 请参阅支持的语言列表。Google 会经常更新支持的语言,所以此列表可能并不详尽。
    • 如果未提供 language,地理编码器会按照 Accept-Language 中的指定尝试使用首选语言,或发出请求的网域的当地语言。
    • 地理编码器会尽力提供用户和当地人都能看懂的街道地址。为实现这一目标,它会以当地语言返回街道地址,然后在必要时按照首选语言将其直译为用户能看懂的文字。所有其他地址均以首选语言返回。地址部分均以同一语言返回,该语言是从第一部分选择的语言。
    • 如果名称在首选语言中没有对应项,地理编码器会使用最接近的匹配项。
    • 首选语言对 API 选择返回的结果集以及结果的返回顺序影响较小。地理编码器对缩写词的解读因语言而异,例如街道类型的缩写词,或者在一种语言中有效但在其他语言中无效的同义词。例如,在匈牙利语中,utcatér 是街道的同义词。
  • region – 地区代码,指定为一个 ccTLD(“顶级域名”)双字符值。此参数只会影响,而不会完全限制地理编码器中的结果。(如需了解详细信息,请参阅下面的地区偏向。)
  • components – 组成部分过滤器,用管道符号 (|) 分隔。每个组成部分过滤器由一个 component:value 对组成,将完全限制地理编码器中的结果。如需了解详细信息,请参阅下面的组成部分过滤

地理编码响应

地理编码响应以 URL 请求路径中 output 标志指示的格式返回。

在此示例中,Google Maps 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 Pkwy",
               "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 Parkway, Mountain View, CA 94043, USA",
         "geometry" : {
            "location" : {
               "lat" : 37.4224764,
               "lng" : -122.0842499
            },
            "location_type" : "ROOFTOP",
            "viewport" : {
               "northeast" : {
                  "lat" : 37.4238253802915,
                  "lng" : -122.0829009197085
               },
               "southwest" : {
                  "lat" : 37.4211274197085,
                  "lng" : -122.0855988802915
               }
            }
         },
         "place_id" : "ChIJ2eUgeAK6j4ARbn5u_wAGqWA",
         "types" : [ "street_address" ]
      }
   ],
   "status" : "OK"
}

请注意,JSON 响应包含两个根元素:

  • "status" 包含请求的元数据。请参阅下面的状态代码
  • "results" 包含一个有关地理编码地址信息和几何信息的数组。

虽然当地址查询比较模糊时,地理编码器可能返回多个结果,但通常地址查找只返回 "results" 数组中的一个条目。

请注意,如果您想从结果中提取值,通常需要对这些结果进行解析。JSON 的解析相对容易。如需了解一些推荐的设计模式,请参阅解析 JSON

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>
  <place_id>ChIJ2eUgeAK6j4ARbn5u_wAGqWA</place_id>
 </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,就可能会发生这种情况。
  • "OVER_QUERY_LIMIT" 表示您已超出配额。
  • "REQUEST_DENIED" 表示系统已拒绝您的请求。
  • "INVALID_REQUEST" 一般表示缺少查询(addresscomponentslatlng)。
  • "UNKNOWN_ERROR" 表示由于服务器发生错误,因此无法处理该请求。如果您重试一次,请求可能会成功

错误消息

当地理编码器返回 OK 以外的状态代码时,地理编码响应对象中可能会包含一个附加的 error_message 字段。此字段更详细地说明了给定状态代码背后的原因。

:此字段不保证始终出现,并且其内容可能会更改。

结果

当地理编码器返回结果时,会将这些结果放在一个 (JSON) results 数组中。即使地理编码器没有返回任何结果(例如,如果地址不存在),它仍然会返回一个空的 results 数组。(XML 响应包含零个或更多个 <result> 元素。)

典型的结果由以下字段组成:

  • types[] 数组表示返回结果的类型。此数组包含一组标记(可能为零个或多个),用于标识结果中所返回特征的类型。例如,“芝加哥”的地理编码返回“locality”,这表明“芝加哥”是一个城市,并且还返回“political”,这表明它是一个政治实体。

  • formatted_address:是一个包含此位置可人工读取的地址的字符串。通常此地址相当于“邮政地址”,有时会因国家/地区而异。(请注意,由于许可限制,某些国家(如英国)不允许发布真实的邮政地址。)此地址通常由一个或多个地址组成部分组成。例如,地址“111 8th Avenue, New York, NY”包含以下地址组成部分:“111”(街道号)、“8th Avenue”(道路)、“New York”(城市)和“NY”(美国的一个州)。这些地址组成部分包含如下所述的附加信息。

  • address_components[] 是包含独立的地址组成部分的数组,如上所述。通常,每个 address_component 均包含:

    • types[],一个表示地址组成部分类型的数组。
    • long_name 是地理编码器返回的地址组成部分的完整文本说明或名称。
    • short_name 是地址组成部分的文本名称缩写(如有)。例如,Alaska 州的地址组成部分可以有 long_name“Alaska”和 short_name“AK”(使用双字母邮政缩写表示)。

    请注意,address_components[] 中包含的地址组成部分可能比 formatted_address 中记录的更多。

  • postcode_localities[] 是一个数组,表示一个邮政编码中包含的所有地方。只有当结果是一个包含多个地方的邮政编码时,才会有此数组。
  • geometry 包含以下信息:

    • location:其中包含地理编码经度、纬度值。对于普通的地址查找,此字段通常是最重要的。
    • location_type 存储有关指定位置的附加数据。目前支持以下值:

      • "ROOFTOP" 表示返回的结果是一个精确的地理编码,我们使其位置信息精确到街道地址的精度。
      • "RANGE_INTERPOLATED" 表示返回的结果反映了两个精确点(例如交叉路口)之间用内插法计算得到的近似值(通常在道路上)。当某个街道地址的 rooftop 地理编码不可用时,通常会返回内插值结果。
      • "GEOMETRIC_CENTER" 表示返回的结果是某个位置(如多段线(例如街道)或多边形(地区))的几何中心。
      • "APPROXIMATE" 表示返回的结果是近似值。
    • viewport 包含用于显示返回结果的推荐视口,指定为两个纬度、经度值,分别定义视口边框的 southwestnortheast 角。视口通常用来在向用户显示结果时为该结果加边框。
    • bounds(可选返回)存储可完全包含返回结果的边框。请注意,这些边界可能与推荐的视口不一致。(例如,旧金山包含费拉隆岛,理论上它是这个城市的一部分,但可能不应该在视口中返回。)
  • partial_match 表示虽然地理编码器能够匹配所请求的地址的一部分,但它未能返回原始请求的精确匹配项。您不妨检查一下原始请求中是否有拼写错误和/或地址不完整的情况。

    对于请求中所传递的行政区划内不存在的街道地址,最常发生部分匹配的情况。当请求与同一行政区划中的两个或更多位置相匹配时,也可能会返回部分匹配。例如,“21 Henr St, Bristol, UK”将返回 Henry Street 和 Henrietta Street 这两项部分匹配结果。请注意,如果请求中包含拼写错误的地址组成部分,地理编码服务可能会建议一个备选地址。以这种方式触发的建议也将标记为部分匹配。

  • place_id 是唯一一个可以与其他 Google API 结合使用的标识符。例如,您可以在 Google Places API 请求中使用 place_id 获取当地企业的详情,如电话号码、营业时间、用户评论等。请参阅地点 ID 概览

由于不能保证对 Google Maps Geocoding API 请求的个别响应的格式准确,因此您永远不应该假定元素处于绝对位置。(特别是,Geocoding API 响应中 address_components 的数量会根据请求的地址而有所不同,并且可以随时间而改变。)相反,您应该解析响应,并通过表达式选择合适的值。如需了解详细信息,请参阅解析 Web 服务响应

地址类型和地址组成部分类型

结果中的 types[] 数组表示地址类型。地址类型的示例包括街道地址、国家/地区或政治实体。在 address_components[] 中也有一个 types[] 数组,用来表示地址各个部分的类型。示例包括门牌号码或国家/地区。(以下是类型的完整列表。)地址可能有多种类型。这些类型可能会被视为“标记”。例如,许多城市都标有 politicallocality 类型。

地理编码器以地址类型和地址组成部分类型数组这两种形式支持并返回以下类型:

  • 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:表示国家/地区级别以下的五级行政实体。此类型表示较小的行政区划单位。并非所有国家都设有这类行政级别
  • colloquial_area:表示实体的常用替代名称
  • locality 表示合并的城市或城镇政治实体。
  • ward 表示一种特定的日本行政区划类型,以便于区分某个日本地址中的多个行政区划组成部分。
  • sublocality:表示 locality 以下的一级行政实体。某些位置可能会收到其他类型之一:从 sublocality_level_1sublocality_level_5。每个 sublocality 级别都是一个行政实体。数字越大,表示的地理区域越小
  • neighborhood 表示已命名的街区
  • premise 表示已命名的位置,通常是具有常见名称的一栋或一群建筑物
  • subpremise 表示指定位置以下的一级实体,通常是同名建筑群中的单个建筑物
  • postal_code 表示邮政编码,用于国内的地址邮寄。
  • natural_feature:表示著名的自然景观
  • airport:表示机场
  • park:表示已命名的公园。
  • point_of_interest 表示已命名的景点。通常,这些“景点”是不容易归入其他类别的著名地方实体,如“帝国大厦”或“自由女神像”。

空的类型列表表示特殊的地址组成部分没有对应的已知类型,例如法国的地方 (Lieu-dit)。

除了上述类型之外,地址组成部分还可能包括下列类型。

:此列表并不全面,并且随时可能更改。

  • floor:表示某个建筑物地址的楼层
  • establishment 通常表示某个尚未归类的地方。
  • point_of_interest 表示已命名的景点。
  • parking 表示停车场或停车设施。
  • post_box 表示特定的邮政信箱。
  • postal_town 表示地理区域的分组,如 localitysublocality,在某些国家/地区用于邮寄地址。
  • room 表示某个建筑物地址的房间。
  • street_number 表示确切的门牌号码。
  • bus_stationtrain_stationtransit_station 表示巴士、火车或公交车站的位置。

视口偏向

在地理编码请求中,您可以指示让地理编码服务倾向于使用某个给定视口(表示为边框)中的结果。您可以通过设置 bounds 参数在请求 URL 中执行此操作。请注意,偏向只是倾向于使用边界以内的结果;如果在这些边界之外存在更相关的结果,也可能会将这些结果包括在内。

bounds 参数定义了此边框的西南角和东北角的纬度/经度坐标,并使用管道字符 (|) 分隔这些坐标。

例如,“温内特卡”的地理编码一般会返回芝加哥的以下郊区:

请求:

https://maps.googleapis.com/maps/api/geocode/json?address=Winnetka&key=YOUR_API_KEY

响应:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Winnetka",
               "short_name" : "Winnetka",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "New Trier",
               "short_name" : "New Trier",
               "types" : [ "administrative_area_level_3", "political" ]
            },
            {
               "long_name" : "Cook County",
               "short_name" : "Cook County",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "Illinois",
               "short_name" : "IL",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United States",
               "short_name" : "US",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Winnetka, IL, USA",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 42.1282269,
                  "lng" : -87.7108162
               },
               "southwest" : {
                  "lat" : 42.0886089,
                  "lng" : -87.7708629
               }
            },
            "location" : {
               "lat" : 42.10808340000001,
               "lng" : -87.735895
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 42.1282269,
                  "lng" : -87.7108162
               },
               "southwest" : {
                  "lat" : 42.0886089,
                  "lng" : -87.7708629
               }
            }
         },
         "place_id" : "ChIJW8Va5TnED4gRY91Ng47qy3Q",
         "types" : [ "locality", "political" ]
      }
   ],
   "status" : "OK"
}

然而,添加一个为洛杉矶圣费尔南多谷定义边框的 bounds 参数会使得此地理编码返回位于该位置的名为“温内特卡”的邻近地区:

请求:

https://maps.googleapis.com/maps/api/geocode/json?address=Winnetka&bounds=34.172684,-118.604794|34.236144,-118.500938&key=YOUR_API_KEY

响应:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Winnetka",
               "short_name" : "Winnetka",
               "types" : [ "neighborhood", "political" ]
            },
            {
               "long_name" : "Los Angeles",
               "short_name" : "LA",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "Los Angeles County",
               "short_name" : "Los Angeles 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" ]
            }
         ],
         "formatted_address" : "Winnetka, Los Angeles, CA, USA",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 34.2355209,
                  "lng" : -118.5534191
               },
               "southwest" : {
                  "lat" : 34.1854649,
                  "lng" : -118.588536
               }
            },
            "location" : {
               "lat" : 34.2048586,
               "lng" : -118.5739621
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 34.2355209,
                  "lng" : -118.5534191
               },
               "southwest" : {
                  "lat" : 34.1854649,
                  "lng" : -118.588536
               }
            }
         },
         "place_id" : "ChIJ0fd4S_KbwoAR2hRDrsr3HmQ",
         "types" : [ "neighborhood", "political" ]
      }
   ],
   "status" : "OK"
}

地区偏向

在地理编码响应中,Google Maps Geocoding API 返回受发送请求地区(通常是国家)影响的地址结果。例如,在美国的某个区域和在西班牙搜索“San Francisco”,可能会返回不同的结果。

您可以使用 region 参数将 Google Maps Geocoding API 设置为返回偏向于特定地区的结果。该参数带有指定地区偏向的 ccTLD(国家代码顶级域)自变量。大多数 ccTLD 代码与 ISO 3166-1 代码相同,但有一些明显的例外。例如,英国的国家代码顶级域名为“uk”(.co.uk),而其 ISO 3166-1 代码却是“gb”(专指“大不列颠及北爱尔兰联合王国”这一实体)。

地理编码结果可以偏向于正式推出了主要 Google 地图应用的每个区域。请注意,偏向只是倾向于使用某个特定区域的结果;如果在此区域以外存在更相关的结果,也可能会将这些结果包括在内。

例如,由于 Google Maps 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.4547053
               },
               "southwest" : {
                  "lat" : 41.580266,
                  "lng" : -83.69423700000002
               }
            },
            "location" : {
               "lat" : 41.6639383,
               "lng" : -83.55521200000001
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 41.732844,
                  "lng" : -83.4547053
               },
               "southwest" : {
                  "lat" : 41.580266,
                  "lng" : -83.69423700000002
               }
            }
         },
         "place_id" : "ChIJeU4e_C2HO4gRRcM6RZ_IPHw",
         "types" : [ "locality", "political" ]
      },
      {
         "address_components" : [
            {
               "long_name" : "Toledo",
               "short_name" : "Toledo",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "Lincoln County",
               "short_name" : "Lincoln County",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "Oregon",
               "short_name" : "OR",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United States",
               "short_name" : "US",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Toledo, OR, USA",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 44.6383219,
                  "lng" : -123.9129439
               },
               "southwest" : {
                  "lat" : 44.598776,
                  "lng" : -123.954585
               }
            },
            "location" : {
               "lat" : 44.621507,
               "lng" : -123.9384478
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 44.6383219,
                  "lng" : -123.9129439
               },
               "southwest" : {
                  "lat" : 44.598776,
                  "lng" : -123.954585
               }
            }
         },
         "place_id" : "ChIJmcjO1AjUwVQRDsRYrfWvzyo",
         "types" : [ "locality", "political" ]
      },
      {
         "address_components" : [
            {
               "long_name" : "Toledo",
               "short_name" : "Toledo",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "Toledo",
               "short_name" : "Toledo",
               "types" : [ "administrative_area_level_3", "political" ]
            },
            {
               "long_name" : "Tama County",
               "short_name" : "Tama County",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "Iowa",
               "short_name" : "IA",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United States",
               "short_name" : "US",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Toledo, IA, USA",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 42.00388600000001,
                  "lng" : -92.56695289999999
               },
               "southwest" : {
                  "lat" : 41.9784431,
                  "lng" : -92.60007299999999
               }
            },
            "location" : {
               "lat" : 41.9972134,
               "lng" : -92.5835266
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 42.00388600000001,
                  "lng" : -92.56695289999999
               },
               "southwest" : {
                  "lat" : 41.9784431,
                  "lng" : -92.60007299999999
               }
            }
         },
         "place_id" : "ChIJvwoVNEOE74cR3oQfIk7m6fU",
         "types" : [ "locality", "political" ]
      },
      {
         "address_components" : [
            {
               "long_name" : "Toledo",
               "short_name" : "Toledo",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "Lewis County",
               "short_name" : "Lewis County",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "Washington",
               "short_name" : "WA",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United States",
               "short_name" : "US",
               "types" : [ "country", "political" ]
            },
            {
               "long_name" : "98591",
               "short_name" : "98591",
               "types" : [ "postal_code" ]
            }
         ],
         "formatted_address" : "Toledo, WA 98591, USA",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 46.44799889999999,
                  "lng" : -122.8419249
               },
               "southwest" : {
                  "lat" : 46.43233009999999,
                  "lng" : -122.85575
               }
            },
            "location" : {
               "lat" : 46.4398305,
               "lng" : -122.846783
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 46.44799889999999,
                  "lng" : -122.8419249
               },
               "southwest" : {
                  "lat" : 46.43233009999999,
                  "lng" : -122.85575
               }
            }
         },
         "place_id" : "ChIJPw9m6cb4k1QRyA5L3wI_dRM",
         "types" : [ "locality", "political" ]
      }
   ],
   "status" : "OK"
}

设置了 region=es(西班牙)后,“Toledo”的地理编码请求将返回西班牙的城市。请求:

https://maps.googleapis.com/maps/api/geocode/json?address=Toledo&region=es&key=YOUR_API_KEY

响应:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Toledo",
               "short_name" : "Toledo",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "Toledo",
               "short_name" : "Toledo",
               "types" : [ "administrative_area_level_4", "political" ]
            },
            {
               "long_name" : "Vega de Toledo",
               "short_name" : "Vega de Toledo",
               "types" : [ "administrative_area_level_3", "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, Toledo, Spain",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 39.88605099999999,
                  "lng" : -3.9192423
               },
               "southwest" : {
                  "lat" : 39.8383676,
                  "lng" : -4.0629256
               }
            },
            "location" : {
               "lat" : 39.8628316,
               "lng" : -4.027323099999999
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 39.88605099999999,
                  "lng" : -3.9192423
               },
               "southwest" : {
                  "lat" : 39.8383676,
                  "lng" : -4.0629256
               }
            }
         },
         "place_id" : "ChIJ8f21C60Lag0R_q11auhbf8Y",
         "types" : [ "locality", "political" ]
      }
   ],
   "status" : "OK"
}

组成部分过滤

在地理编码响应中,Google Maps Geocoding API 可以返回限制在某个特定区域的地址结果。使用 components 过滤器来指定限制。过滤器由一个 component:value 对列表组成,这些键值对用管道符号 (|) 分隔。只有符合所有过滤器的结果才会被返回。过滤器值支持与其他地理编码请求相同的用于拼写校正和部分匹配的方法。如果地理编码结果部分匹配某个组成部分过滤器,它将在响应中包含 partial_match 字段。

可以过滤的 components 包括:

  • route 用来匹配路由的长名称或短名称。
  • locality 既可以匹配 locality 类型,也可以匹配 sublocality 类型。
  • administrative_area 用来匹配所有 administrative_area 级别。
  • postal_code 用来匹配 postal_codepostal_code_prefix
  • country 用来匹配国家/地区名称或两个字母的 ISO 3166-1 国家/地区代码。

    :我们按照 ISO 标准来定义国家,因此使用国家对应的 ISO 代码进行过滤的效果最好。

:要么在地址参数中指定每个地址组成部分,要么将其指定为组成部分过滤器,这两种方式只能选择其一,不可同时使用。这样做可能会导致 ZERO_RESULTS

设置了 components=country:ES 后,“Santa Cruz”的地理编码将返回西班牙加那利群岛的圣克鲁斯特内里费。请求:

https://maps.googleapis.com/maps/api/geocode/json?address=santa+cruz&components=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" : "Santa Cruz de Tenerife",
               "types" : [ "administrative_area_level_4", "political" ]
            },
            {
               "long_name" : "Anaga",
               "short_name" : "Anaga",
               "types" : [ "administrative_area_level_3", "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, 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"
}

包含组成部分过滤器的查询将只返回匹配该过滤器的地理编码结果。如果没有找到匹配项,地理编码器会返回一个与该过滤器本身相匹配的结果。请求:

https://maps.googleapis.com/maps/api/geocode/json?address=Torun&components=administrative_area:TX|country:US&key=YOUR_API_KEY

响应:

{
   "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.5007041,
                  "lng" : -93.5080389
               },
               "southwest" : {
                  "lat" : 25.8371638,
                  "lng" : -106.6456461
               }
            },
            "location" : {
               "lat" : 31.9685988,
               "lng" : -99.9018131
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 36.5015087,
                  "lng" : -93.5080389
               },
               "southwest" : {
                  "lat" : 25.8371638,
                  "lng" : -106.6456461
               }
            }
         },
         "partial_match" : true,
         "place_id" : "ChIJSTKCCzZwQIYRPN4IGI8c6xY",
         "types" : [ "administrative_area_level_1", "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 过滤器时,可以在无地址参数的情况下进行查询,但不能在没有值的情况下指定组成部分。请求:

https://maps.googleapis.com/maps/api/geocode/json?components=route:Annegatan|administrative_area:Helsinki|country:Finland&key=YOUR_API_KEY

响应:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Annegatan",
               "short_name" : "Annegatan",
               "types" : [ "route" ]
            },
            {
               "long_name" : "Helsingfors",
               "short_name" : "Helsingfors",
               "types" : [ "administrative_area_level_3", "political" ]
            },
            {
               "long_name" : "Finland",
               "short_name" : "FI",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Annegatan, Helsingfors, Finland",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 60.168997,
                  "lng" : 24.9427959
               },
               "southwest" : {
                  "lat" : 60.1626627,
                  "lng" : 24.934
               }
            },
            "location" : {
               "lat" : 60.1657808,
               "lng" : 24.938451
            },
            "location_type" : "GEOMETRIC_CENTER",
            "viewport" : {
               "northeast" : {
                  "lat" : 60.168997,
                  "lng" : 24.9427959
               },
               "southwest" : {
                  "lat" : 60.1626627,
                  "lng" : 24.934
               }
            }
         },
         "place_id" : "ChIJARW7C8sLkkYRgl4je4-RPUM",
         "types" : [ "route" ]
      },
      {
         "address_components" : [
            {
               "long_name" : "Annevägen",
               "short_name" : "Annevägen",
               "types" : [ "route" ]
            },
            {
               "long_name" : "Vanda",
               "short_name" : "Vanda",
               "types" : [ "administrative_area_level_3", "political" ]
            },
            {
               "long_name" : "Finland",
               "short_name" : "FI",
               "types" : [ "country", "political" ]
            },
            {
               "long_name" : "01420",
               "short_name" : "01420",
               "types" : [ "postal_code" ]
            }
         ],
         "formatted_address" : "Annevägen, 01420 Vanda, Finland",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 60.3282738,
                  "lng" : 25.1162163
               },
               "southwest" : {
                  "lat" : 60.32564009999999,
                  "lng" : 25.1076474
               }
            },
            "location" : {
               "lat" : 60.3271069,
               "lng" : 25.1118046
            },
            "location_type" : "GEOMETRIC_CENTER",
            "viewport" : {
               "northeast" : {
                  "lat" : 60.3283059302915,
                  "lng" : 25.1162163
               },
               "southwest" : {
                  "lat" : 60.32560796970849,
                  "lng" : 25.1076474
               }
            }
         },
         "partial_match" : true,
         "place_id" : "ChIJ3UJCNt4GkkYR8-_a8Dh25kA",
         "types" : [ "route" ]
      },
      {
         "address_components" : [
            {
               "long_name" : "Anneplatsen",
               "short_name" : "Anneplatsen",
               "types" : [ "route" ]
            },
            {
               "long_name" : "Helsingfors",
               "short_name" : "Helsingfors",
               "types" : [ "administrative_area_level_3", "political" ]
            },
            {
               "long_name" : "Finland",
               "short_name" : "FI",
               "types" : [ "country", "political" ]
            },
            {
               "long_name" : "00100",
               "short_name" : "00100",
               "types" : [ "postal_code" ]
            }
         ],
         "formatted_address" : "Anneplatsen, 00100 Helsingfors, Finland",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 60.1695664,
                  "lng" : 24.9357125
               },
               "southwest" : {
                  "lat" : 60.168997,
                  "lng" : 24.934
               }
            },
            "location" : {
               "lat" : 60.1692741,
               "lng" : 24.9348016
            },
            "location_type" : "GEOMETRIC_CENTER",
            "viewport" : {
               "northeast" : {
                  "lat" : 60.17063068029151,
                  "lng" : 24.9362052302915
               },
               "southwest" : {
                  "lat" : 60.1679327197085,
                  "lng" : 24.9335072697085
               }
            }
         },
         "partial_match" : true,
         "place_id" : "ChIJeahMqswLkkYR2vQfG1nHI3M",
         "types" : [ "route" ]
      }
   ],
   "status" : "OK"
}

反向地理编码(地址查找)

术语地理编码一般是指将可人工读取的地址转换为地图上的某个位置。与之相反,将地图上的某个位置转换为可人工读取的地址的过程,就称为反向地理编码

反向地理编码请求中的必填参数

  • latlng – 经纬度值,用于指定希望获得其最接近的、可人工读取的地址的位置。
         或者
    place_id – 希望获得其可人工读取地址的地点的地点 ID。地点 ID 是唯一一个可以与其他 Google API 结合使用的标识符。例如,您可以使用由 Google Maps Roads API 返回的 placeID 来获取某个拍摄点的地址。如需了解有关地点 ID 的详细信息,请参阅地点 ID 概览。只有当请求包括 API 密钥或 Google Maps APIs Premium Plan 客户端 ID 时,才能指定地点 ID。
  • key – 您的应用的 API 密钥。此密钥可以标识您的应用,以便进行配额管理。了解如何获取密钥

    注:Google Maps APIs Premium Plan 客户可以在反向 Geocoding 请求中使用 API 密钥或有效的客户端 ID 和数字签名。获取有关 Premium Plan 客户身份验证参数的更多信息。

反向地理编码请求中的可选参数:

您可以将下列可选参数包括在反向地理编码请求中:

  • language – 返回结果时使用的语言。
    • 请参阅支持的语言列表。Google 会经常更新支持的语言,所以此列表可能并不详尽。
    • 如果未提供 language,地理编码器会按照 Accept-Language 中的指定尝试使用首选语言,或发出请求的网域的当地语言。
    • 地理编码器会尽力提供用户和当地人都能看懂的街道地址。为实现这一目标,它会以当地语言返回街道地址,然后在必要时按照首选语言将其直译为用户能看懂的文字。所有其他地址均以首选语言返回。地址部分均以同一语言返回,该语言是从第一部分选择的语言。
    • 如果名称在首选语言中没有对应项,地理编码器会使用最接近的匹配项。
  • result_type – 一个或多个地址类型,用管道符号 (|) 分隔。地址类型的示例:countrystreet_addresspostal_code。如需查看允许值的完整列表,请参阅此页面上的地址类型。如果指定了一种类型,会将结果限制于这种类型。如果指定了多种类型,该 API 将返回匹配其中任何类型的所有地址。:此参数仅适用于包括 API 密钥或客户端 ID 的请求。
  • location_type – 一个或多个位置类型,用管道符号 (|) 分隔。如果指定了一种类型,会将结果限制于这种类型。如果指定了多种类型,该 API 将返回匹配其中任何类型的所有地址。:此参数仅适用于包括 API 密钥或客户端 ID 的请求。支持使用以下值:
    • "ROOFTOP" 将结果限制为我们使其位置信息精确到街道地址精度的地址。
    • "RANGE_INTERPOLATED" 将结果限制为反映了两个精确点(例如交叉路口)之间用内插法计算得到的近似值(通常在道路上)的地址。内插的范围通常表示某个街道地址的 rooftop 地理编码不可用。
    • "GEOMETRIC_CENTER" 将结果限制为某个位置(如多段线(例如街道)或多边形(地区))的几何中心。
    • "APPROXIMATE" 将结果限制为是近似值的地址。

如果 result_typelocation_type 限制同时存在,那么该 API 将只返回同时匹配 result_typelocation_type 限制的结果。

纬度/经度的反向地理编码

以下查询包含了布鲁克林某个位置的纬度/经度值:

https://maps.googleapis.com/maps/api/geocode/json?latlng=40.714224,-73.961452&key=YOUR_API_KEY

注:确保在将纬度和经度值传入 latlng 参数时,两者之间没有空格。

上述查询返回以下结果:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "277",
               "short_name" : "277",
               "types" : [ "street_number" ]
            },
            {
               "long_name" : "Bedford Avenue",
               "short_name" : "Bedford Ave",
               "types" : [ "route" ]
            },
            {
               "long_name" : "Williamsburg",
               "short_name" : "Williamsburg",
               "types" : [ "neighborhood", "political" ]
            },
            {
               "long_name" : "Brooklyn",
               "short_name" : "Brooklyn",
               "types" : [ "sublocality", "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" ]
            }
         ],
         "formatted_address" : "277 Bedford Avenue, Brooklyn, NY 11211, USA",
         "geometry" : {
            "location" : {
               "lat" : 40.714232,
               "lng" : -73.9612889
            },
            "location_type" : "ROOFTOP",
            "viewport" : {
               "northeast" : {
                  "lat" : 40.7155809802915,
                  "lng" : -73.9599399197085
               },
               "southwest" : {
                  "lat" : 40.7128830197085,
                  "lng" : -73.96263788029151
               }
            }
         },
         "place_id" : "ChIJd8BlQ2BZwokRAFUEcm_qrcA",
         "types" : [ "street_address" ]
      },

  ... Additional results[] ...

请注意,反向地理编码器返回了多个结果。"formatted_address" 的结果不仅有邮政地址,还包括对某个位置的任何地理命名方式。例如,对芝加哥市的某个点进行地理编码时,地理编码的点可以表示为街道地址、城市(芝加哥)、所在州(伊利诺伊州)或国家/地区(美国)。所有这些都是地理编码器的“地址”。反向地理编码器返回这些类型中的任何一种作为有效结果。

反向地理编码器会匹配政治实体(国家/地区、省、市和街区)、街道地址及邮政编码。

由以前的查询返回的 formatted_address 值的完整列表如下所示。

"formatted_address" : "277 Bedford Avenue, Brooklyn, NY 11211, USA",
"formatted_address" : "Grand St/Bedford Av, Brooklyn, NY 11211, USA",
"formatted_address" : "Grand St/Bedford Av, Brooklyn, NY 11249, USA",
"formatted_address" : "Bedford Av/Grand St, Brooklyn, NY 11211, USA",
"formatted_address" : "Brooklyn, NY 11211, USA",
"formatted_address" : "Williamsburg, Brooklyn, NY, USA",
"formatted_address" : "Brooklyn, NY, USA",
"formatted_address" : "New York, NY, USA",
"formatted_address" : "New York, USA",
"formatted_address" : "United States",

通常,返回的地址按精确度从最具体到最不具体的顺序排列;正如本例中所示,最准确的地址在结果中摆在最突出的位置。请注意,我们会返回不同类型的地址,从最具体的街道地址到不那么具体的政治实体,如街区、市、县、州等。如果您想匹配特定类型的地址,请参阅以下有关按类型限制结果的部分。

注:反向地理编码是一种估计。地理编码器将尝试在某一误差限度范围内查找最接近的可寻址位置。如果没有找到匹配项,地理编码器会返回零个结果。

地点 ID 的反向地理编码

以下查询包含了布鲁克林某个位置的地点 ID:

https://maps.googleapis.com/maps/api/geocode/json?place_id=ChIJd8BlQ2BZwokRAFUEcm_qrcA&key=YOUR_API_KEY

上述查询返回以下结果:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "277",
               "short_name" : "277",
               "types" : [ "street_number" ]
            },
            {
               "long_name" : "Bedford Ave",
               "short_name" : "Bedford Ave",
               "types" : [ "route" ]
            },
            {
               "long_name" : "Williamsburg",
               "short_name" : "Williamsburg",
               "types" : [ "neighborhood", "political" ]
            },
            {
               "long_name" : "Brooklyn",
               "short_name" : "Brooklyn",
               "types" : [ "sublocality_level_1", "sublocality", "political" ]
            },
            {
               "long_name" : "Kings County",
               "short_name" : "Kings County",
               "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" ]
            }
         ],
         "formatted_address" : "277 Bedford Ave, Brooklyn, NY 11211, USA",
         "geometry" : {
            "location" : {
               "lat" : 40.714232,
               "lng" : -73.9612889
            },
            "location_type" : "ROOFTOP",
            "viewport" : {
               "northeast" : {
                  "lat" : 40.7155809802915,
                  "lng" : -73.9599399197085
               },
               "southwest" : {
                  "lat" : 40.7128830197085,
                  "lng" : -73.96263788029151
               }
            }
         },
         "partial_match" : true,
         "place_id" : "ChIJd8BlQ2BZwokRAFUEcm_qrcA",
         "types" : [ "street_address" ]
      }
   ],
   "status" : "OK"
}

受类型限制的反向地理编码

以下示例将返回的地址限制为位置类型是 ROOFTOP 且地址类型是 street_address 的地址。

https://maps.googleapis.com/maps/api/geocode/json?latlng=40.714224,-73.961452&location_type=ROOFTOP&result_type=street_address&key=YOUR_API_KEY

:这些限制只适用于反向地理编码。

反向地理编码响应

反向地理编码响应的格式与地理编码响应相同。请参阅地理编码响应。下面是反向地理编码响应中可能出现的状态代码。

反向地理编码状态代码

地理编码响应对象中的 "status" 字段包含了请求的状态,还可能包含调试信息,以帮助您查明反向地理编码不工作的原因。"status" 字段可以包含以下值:

  • "OK" 表示未出现任何错误,并且至少返回了一个地址。
  • "ZERO_RESULTS" 表示反向地理编码成功,但未返回任何结果。如果向地理编码器传递了某个偏远位置的 latlng 参数,就可能会发生这种情况。
  • "OVER_QUERY_LIMIT" 表示您已超出配额。
  • "REQUEST_DENIED" 表示系统已拒绝该请求。这可能是因为该请求包含了 result_typelocation_type 参数,但未包含 API 密钥或客户端 ID。
  • "INVALID_REQUEST" 通常表示下列情况之一:
    • 缺少查询(addresscomponentslatlng)。
    • 提供的 result_typelocation_type 无效。
  • "UNKNOWN_ERROR" 表示由于服务器发生错误,因此无法处理该请求。如果您重试一次,请求可能会成功

sensor 参数

Google Maps API 之前要求您将 sensor 参数包括在内,以指示您的应用是否使用传感器来确定用户的位置。但该参数现在不再是必填项。

发送以下问题的反馈:

此网页
Google Maps Geocoding API
Google Maps Geocoding API
需要帮助?请访问我们的支持页面