地理编码服务

使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

概览

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

反向地理编码是将地理坐标转换为便于用户理解的地址的过程(请参阅反向地理编码(地址查询))。

您还可以使用地理编码器查找给定地点 ID 的地址。

Maps JavaScript API 提供了 Geocoder 类,用于根据用户输入动态进行地理编码和反向地理编码。如果您想对已知的静态地址进行地理编码,请参阅地理编码网络服务

开始使用

在使用 Maps JavaScript API 中的地理编码服务之前,请先确保在 Google Cloud Console 中针对您为 Maps JavaScript API 设置的项目中启用了 Geocoding API。

要查看已启用 API 的列表,请执行以下操作:

  1. 转到 Google Cloud Console
  2. 点击选择项目按钮,然后选择您为 Maps JavaScript API 设置的同一项目,然后点击打开
  3. 信息中心的 API 列表中,查找 Geocoding API
  4. 如果您在列表中看到了该 API,就说明一切就绪。如果未列出该 API,请启用:
    1. 在页面顶部,选择 ENABLE API 以显示标签页。或从左侧菜单中选择
    2. 搜索 Geocoding API,然后从结果列表中选择它。
    3. 选择启用。该过程完成后,Geocoding API 会显示在信息中心的 API 列表中。

价格和政策

价格

自 2018 年 7 月 16 日起,地图、路线和地点产品开始采用新的随用随付定价方案。如需详细了解 JavaScript 地理编码服务使用的新价格和用量限额,请参阅 Geocoding API 的用量和结算

速率限制

对于其他请求的限制,请注意以下几点:

无论有多少用户共享同一项目,都会对每个用户会话应用额外的速率限制。首次加载 API 时,系统会为您分配初始请求配额。您使用此配额后,该 API 会对每秒的请求施加速率限制。如果某个时间段内发出的请求过多,API 会返回 OVER_QUERY_LIMIT 响应代码。

基于会话的速率限制可防止将客户端服务用于批量请求(例如批量地理编码)。对于批量请求,请使用 Geocoding API 网络服务

政策

使用地理编码服务时必须遵守 Geocoding API 的相关政策

地理编码请求

Google Maps API 需要调用外部服务器,因此对地理编码服务的访问是异步的。因此,您需要传递一个回调方法,以便在请求完成后执行。此回调方法会对结果进行处理。请注意,地理编码器可能会返回多个结果。

您可以通过在代码中使用 google.maps.Geocoder 构造函数对象来访问 Google Maps API 地理编码服务。Geocoder.geocode() 方法会向地理编码服务发起请求,方法是向其传递一个 GeocoderRequest 对象字面量,其中包含输入字词和一个用于在收到响应后执行的回调方法。

GeocoderRequest 对象字面量包含以下字段:

{
 address: string,
 location: LatLng,
 placeId: string,
 bounds: LatLngBounds,
 componentRestrictions: GeocoderComponentRestrictions,
 region: string
}

必需参数:您必须提供以下字段中的一个(且只有一个):

  • address - 要进行地理编码的地址。

    location - 您希望获取的距离最近的人类可读地址的 LatLng(或 LatLngLiteral)。地理编码器执行反向地理编码。如需了解详情,请参阅反向地理编码

    placeId - 您希望获取的距离最近的人类可读地址的地点 ID。详细了解如何检索地点 ID 的地址

可选参数

  • bounds - 要在其中更显著地使地理编码结果偏向的 LatLngBoundsbounds 参数只会影响,而不会完全限制地理编码器中的结果。请参阅下文,详细了解视口自定义调整
  • componentRestrictions - 用于将结果限制为特定区域。请参阅下文,详细了解组件过滤
  • region - 地区代码,指定为以两个字符(非数字)Unicode 区域子标记的形式指定的代码。在大多数情况下,这些标记直接映射到熟悉的 ccTLD(“顶级域名”)双字符值。region 参数只会影响,而不会完全限制地理编码器中的结果。请参阅下文中有关区域代码偏向的更多信息。

地理编码响应

地理编码服务需要一个在检索到地理编码器结果后执行的回调方法。此回调应依次传递两个参数,以分别存储 resultsstatus 代码。

地理编码结果

GeocoderResult 对象表示单个地理编码结果。地理编码请求可能会返回多个结果对象:

results[]: {
 types[]: string,
 formatted_address: string,
 address_components[]: {
   short_name: string,
   long_name: string,
   postcode_localities[]: string,
   types[]: string
 },
 partial_match: boolean,
 place_id: string,
 postcode_localities[]: string,
 geometry: {
   location: LatLng,
   location_type: GeocoderLocationType
   viewport: LatLngBounds,
   bounds: LatLngBounds
 }
}

这些字段的含义如下:

  • types[] 是一个数组,表示返回结果的地址类型。此数组包含一组零个或多个标记,这些标记用于标识结果中返回的特征类型。例如,对“芝加哥”的地理编码返回“芝加哥”且表示该城市为城市,同时返回“政治”表明它为政治实体。请参阅下文,详细了解地址类型和地址组成部分类型
  • formatted_address 是一个包含此营业地点的人类可读地址的字符串。

    通常该地址相当于邮政地址。请注意,由于许可限制,有些国家/地区(例如英国)不允许发布真实的邮政地址。

    格式化的地址在逻辑上由一个或多个地址组成部分组成。例如,“111 8th Avenue, New York, NY”包含以下组成部分:&q 111”(街道号码)、“8th Avenue”(城市)、“NY”(纽约市)和“NY”(美国的一个州)。

    请勿以编程方式解析格式化的地址。相反,除了 API 格式的地址字段之外,您还应使用 API 响应包含的各个地址组成部分。

  • address_components[] 是包含适用于该地址的单独组件的数组。

    通常,每个地址组成部分都包含以下字段:

    • types[] 是一个数组,表示地址组成部分的类型。请参阅支持的类型列表。
    • long_name 是地址解析器返回的完整文本说明或地址组成部分的名称。
    • short_name 是地址组成部分的缩写文本名称(如果有)。例如,阿拉斯加州的地址组成部分可能具有“阿拉斯加”的 long_nameshort_name 为“AK”的双字母邮政缩写。

    请注意关于 address_components[] 数组的以下事实:

    • 地址组成部分的数组可能包含比 formatted_address 更多的组成部分。
    • formatted_address 中包含的政治实体之外,该数组不一定包含所有政治实体。要检索包含特定地址的所有政治实体,您应使用反向地理编码,将地址的纬度/经度作为参数传递给请求。
    • 响应的格式不能保证各个请求保持不变。具体而言,address_components 数量取决于所请求的地址,并且可能会随着同一地址而不断变化。组件可以更改在数组中的位置。该组件的类型可能会发生变化。特定组件在后续响应中可能会缺失。

    请参阅下文,详细了解地址类型和地址组成部分类型

  • partial_match 表示地理编码器未针对原始请求返回完全匹配,但能够匹配所请求的地址的一部分。您不妨检查一下原始请求中是否有拼写错误和/或地址不完整的情况。

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

  • place_id 是地点的唯一标识符,可用于其他 Google API。例如,您可以将 place_idGoogle Places API 库结合使用,以获取本地商家的详细信息,例如电话号码、营业时间、用户评价等。请参阅地点 ID 概览
  • postcode_localities[] 是一个数组,表示一个邮政编码中包含的所有市行政区,并且仅当结果是包含多个市行政区的邮政编码时才存在。
  • geometry 包含以下信息:

    • location 包含经过地理编码的纬度、经度值。请注意,我们会以 LatLng 对象(而非格式化字符串)的形式返回此位置。
    • location_type 会存储关于指定位置的额外数据,目前支持以下值:
      • ROOFTOP 表示返回的结果反映了精确的地理编码。
      • RANGE_INTERPOLATED 表示返回的结果是一个近似值(通常为道路上的地址),该地址处于两个精确点(例如交叉路口)之间。当某个街道地址的屋顶地理编码不可用时,通常会返回插值结果。
      • GEOMETRIC_CENTER 表示返回的结果是多段线(例如街道)或多边形(区域)的几何中心。
      • APPROXIMATE 表示返回的结果是近似值。

    • viewport 会存储返回结果的推荐视口。
    • bounds(可选返回)用于存储可完全包含返回结果的 LatLngBounds。请注意,这些边界可能与建议的视口不匹配(例如,旧金山包含法拉隆群岛,该岛实际上是旧金山市的一部分,但不应该在视口内返回)。

地理编码器会使用浏览器的首选语言设置或在加载 API JavaScript 时使用 language 参数所指定的语言来返回该地址。(如需了解详情,请参阅本地化。)

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

GeocoderResult 中的 types[] 数组表示地址类型GeocoderAddressComponent 中也可能会返回 types[] 数组,以表示特定地址组成部分的类型。地理编码器返回的地址可能有多种类型;这些类型可能会被视为标记。例如,许多城市都带有 politicallocality 类型标记。

地理编码器在地址类型和地址组成部分类型中均支持并返回以下类型:

  • street_address 表示精确的街道地址。
  • route 表示已命名的路线(例如“US 101”)。
  • intersection 表示主要交叉路口,通常是两条主要道路的交叉路口。
  • political 指示政治实体。此类型通常表示某个民用行政区域的多边形。
  • country 表示国家/地区政治实体,通常是地理编码器返回的最高顺序类型。
  • administrative_area_level_1 表示国家/地区级别以下的一级行政实体。在美国,这类行政级别是指州。并非所有国家/地区都有这些行政级别。在大多数情况下,admin_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_1sublocality_level_5。每个市行政区都是一个行政实体。数字越大,表示地理区域越小。
  • neighborhood 表示已命名的街区
  • premise 表示已命名的位置,通常是同名的建筑物或建筑群
  • subpremise 表示指定位置以下的一级实体,通常是同名建筑群中的一座建筑物
  • plus_code 表示根据纬度和经度推导的编码位置。Plus Code 可在没有街道地址(建筑物没有编号或街道未命名)中用于代替街道地址。如需了解详情,请参阅 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 指示用于某些国家/地区的邮寄地址的分组,如 localitysublocality
  • room 表示建筑物地址的房间号。
  • street_number 表示确切的门牌号码。
  • bus_stationtrain_stationtransit_station 指示公交、火车或公共交通车站的位置。

状态代码

status 代码可能会返回以下某个值:

  • "OK" 表示未发生错误;地址已成功解析,并且至少返回了一个地理编码。
  • "ZERO_RESULTS" 表示地理编码成功,但未返回任何结果。如果向地理编码器传递了不存在的 address,就可能会发生这种情况。
  • "OVER_QUERY_LIMIT" 表示您超出了配额。
  • "REQUEST_DENIED" 表示您的请求已遭拒。不允许网页使用地理编码器。
  • "INVALID_REQUEST" 通常表示缺少查询(addresscomponentslatlng)。
  • "UNKNOWN_ERROR" 表示由于服务器错误而无法处理请求。如果您重试,请求可能会成功。
  • "ERROR" 表示请求超时或联系 Google 服务器时出现问题。如果您重试,请求可能会成功。

在此示例中,我们对地址进行地理编码,并在返回的纬度和经度值处放置标记。请注意,该处理程序会作为匿名函数字面量传递。

  var geocoder;
  var map;
  function initialize() {
    geocoder = new google.maps.Geocoder();
    var latlng = new google.maps.LatLng(-34.397, 150.644);
    var mapOptions = {
      zoom: 8,
      center: latlng
    }
    map = new google.maps.Map(document.getElementById('map'), mapOptions);
  }

  function codeAddress() {
    var address = document.getElementById('address').value;
    geocoder.geocode( { 'address': address}, function(results, status) {
      if (status == 'OK') {
        map.setCenter(results[0].geometry.location);
        var marker = new google.maps.Marker({
            map: map,
            position: results[0].geometry.location
        });
      } else {
        alert('Geocode was not successful for the following reason: ' + status);
      }
    });
  }

<body onload="initialize()">
 <div id="map" style="width: 320px; height: 480px;"></div>
  <div>
    <input id="address" type="textbox" value="Sydney, NSW">
    <input type="button" value="Encode" onclick="codeAddress()">
  </div>
</body>

查看示例。

视口偏向

您可以指示地理编码服务优先显示指定视口(表示为边界框)内的结果。为此,您可以在 GeocoderRequest 对象字面量中设置 bounds 参数,以定义此视口的边界。请注意,偏向仅会优先显示边界内的结果;如果边界外的结果的相关程度更高,您也可将其包含在内。

例如,针对“Winnetka”(温内特卡)的地理编码通常会返回芝加哥近郊地区的地址,具体如下:

{
  "types":["locality","political"],
  "formatted_address":"Winnetka, IL, USA",
  "address_components":[{
    "long_name":"Winnetka",
    "short_name":"Winnetka",
    "types":["locality","political"]
  },{
    "long_name":"Illinois",
    "short_name":"IL",
    "types":["administrative_area_level_1","political"]
  },{
    "long_name":"United States",
    "short_name":"US",
    "types":["country","political"]
  }],
  "geometry":{
    "location":[ -87.7417070, 42.1083080],
    "location_type":"APPROXIMATE"
  },
  "place_id": "ChIJW8Va5TnED4gRY91Ng47qy3Q"
}

但是,如果指定 bounds 参数为洛杉矶的圣费尔南多谷定义边界框,则会导致此地理编码返回位于该位置附近的名为“Winnetka”的街区:

{
  "types":["sublocality","political"],
  "formatted_address":"Winnetka, California, USA",
  "address_components":[{
    "long_name":"Winnetka",
    "short_name":"Winnetka",
    "types":["sublocality","political"]
  },{
    "long_name":"Los Angeles",
    "short_name":"Los Angeles",
    "types":["administrative_area_level_3","political"]
  },{
    "long_name":"Los Angeles",
    "short_name":"Los Angeles",
    "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"]
  }],
  "geometry":{
    "location": [34.213171,-118.571022],
    "location_type":"APPROXIMATE"
  },
  "place_id": "ChIJ0fd4S_KbwoAR2hRDrsr3HmQ"
}

地区代码偏向

您可以使用 region 参数将地理编码服务显式设为返回偏向特定区域的结果。此参数采用地区代码,指定为两个字符(非数字)Unicode 区域子标记。这些标记直接映射到熟悉的 ccTLD(“顶级域名”)双字符值,例如“co.uk”中的“uk”。在某些情况下,region 标记也支持 ISO-3166-1 代码,该代码有时会与 ccTLD 值有所不同(例如,“GB”表示“大不列颠”)。

使用 region 参数时:

  • 请仅指定一个国家或地区。系统会忽略多个值,这可能会导致请求失败。
  • 只能使用两个字符的区域子标记(Unicode CLDR 格式)。所有其他输入都会导致错误。
  • 仅支持 Google Maps Platform 覆盖范围详细信息中列出的国家和地区。

对于 Google 地图主应用提供地理编码服务的每个网域,您都可以向其发送地理编码请求。请注意,偏向仅优先显示特定网域的结果;如果此网域外存在更相关的结果,也可能会将其包含在内。

例如,对“Toledo”的地理编码会返回以下结果,因为地理编码服务的默认区域设置为美国:

{
  "types":["locality","political"],
  "formatted_address":"Toledo, OH, USA",
  "address_components":[{
    "long_name":"Toledo",
    "short_name":"Toledo",
    "types":["locality","political"]
  },{
    "long_name":"Ohio",
    "short_name":"OH",
    "types":["administrative_area_level_1","political"]
  },{
    "long_name":"United States",
    "short_name":"US",
    "types":["country","political"]
  }],
  "place_id": "ChIJeU4e_C2HO4gRRcM6RZ_IPHw"
}

对“Toledo”(托莱多)进行地理编码,其中 region 字段设置为 'es'(西班牙)时,将返回西班牙城市:

{
  "types":["locality","political"],
  "formatted_address":"Toledo, España",
  "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":"Castilla-La Mancha",
    "short_name":"CM",
    "types":["administrative_area_level_1","political"]
  },{
    "long_name":"España",
    "short_name":"ES",
    "types":["country","political"]
  }],
  "place_id": "ChIJ8f21C60Lag0R_q11auhbf8Y"
}

组成部分过滤

您可以使用组件过滤器将地理编码服务设置为返回仅限特定区域的地址结果。在 componentRestrictions 参数中指定过滤条件。过滤器值支持与其他地理编码请求相同的拼写纠正和部分匹配方法。

地理编码器仅返回与所有组件过滤条件匹配的结果。也就是说,它会以 AND(而不是 OR)评估过滤器规范。

组件过滤条件包含以下一项或多项:

  • route 匹配路由的长名称或短名称。
  • locality 与市行政区和子市行政区类型匹配。
  • administrativeArea 匹配所有行政区。
  • postalCode 与邮政编码和邮政编码前缀匹配。
  • country 与国家/地区名称或两个字母的 ISO 3166-1 国家/地区代码匹配。注意:该 API 遵循 ISO 标准来定义国家/地区,当使用相应国家/地区的相应 ISO 代码时,过滤效果最佳。

以下示例演示了如何使用 componentRestrictions 参数按 countrypostalCode 进行过滤:

function codeAddress() {
geocoder.geocode({
  componentRestrictions: {
    country: 'AU',
    postalCode: '2000'
  }
}, function(results, status) {
  if (status == 'OK') {
    map.setCenter(results[0].geometry.location);
    var marker = new google.maps.Marker({
      map: map,
      position: results[0].geometry.location
    });
  } else {
    window.alert('Geocode was not successful for the following reason: ' + status);
  }
});
}

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

术语“地理编码”通常是指将人类可读的地址转换为地图上的位置。反之,将地图上的位置转换为便于用户理解的地址的过程,就称为反向地理编码。

location 参数中提供以英文逗号分隔的纬度/经度对,而非文本 address

以下示例对纬度/经度值进行地理编码,并将地图中心设为该位置,会显示一个信息窗口,其中包含经过格式化的地址:

TypeScript

function initMap(): void {
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      zoom: 8,
      center: { lat: 40.731, lng: -73.997 },
    }
  );
  const geocoder = new google.maps.Geocoder();
  const infowindow = new google.maps.InfoWindow();

  (document.getElementById("submit") as HTMLElement).addEventListener(
    "click",
    () => {
      geocodeLatLng(geocoder, map, infowindow);
    }
  );
}

function geocodeLatLng(
  geocoder: google.maps.Geocoder,
  map: google.maps.Map,
  infowindow: google.maps.InfoWindow
) {
  const input = (document.getElementById("latlng") as HTMLInputElement).value;
  const latlngStr = input.split(",", 2);
  const latlng = {
    lat: parseFloat(latlngStr[0]),
    lng: parseFloat(latlngStr[1]),
  };

  geocoder
    .geocode({ location: latlng })
    .then((response) => {
      if (response.results[0]) {
        map.setZoom(11);

        const marker = new google.maps.Marker({
          position: latlng,
          map: map,
        });

        infowindow.setContent(response.results[0].formatted_address);
        infowindow.open(map, marker);
      } else {
        window.alert("No results found");
      }
    })
    .catch((e) => window.alert("Geocoder failed due to: " + e));
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;

JavaScript

function initMap() {
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 8,
    center: { lat: 40.731, lng: -73.997 },
  });
  const geocoder = new google.maps.Geocoder();
  const infowindow = new google.maps.InfoWindow();

  document.getElementById("submit").addEventListener("click", () => {
    geocodeLatLng(geocoder, map, infowindow);
  });
}

function geocodeLatLng(geocoder, map, infowindow) {
  const input = document.getElementById("latlng").value;
  const latlngStr = input.split(",", 2);
  const latlng = {
    lat: parseFloat(latlngStr[0]),
    lng: parseFloat(latlngStr[1]),
  };

  geocoder
    .geocode({ location: latlng })
    .then((response) => {
      if (response.results[0]) {
        map.setZoom(11);

        const marker = new google.maps.Marker({
          position: latlng,
          map: map,
        });

        infowindow.setContent(response.results[0].formatted_address);
        infowindow.open(map, marker);
      } else {
        window.alert("No results found");
      }
    })
    .catch((e) => window.alert("Geocoder failed due to: " + e));
}

window.initMap = initMap;
查看示例

试用示例

请注意,在上一个示例中,我们通过选择 results[0] 显示了第一条结果。反向地理编码器通常会返回多个结果。经过地理编码的地址不仅是指邮政地址,还包含对位置进行地理命名的所有方式。例如,对芝加哥市中的一个点进行地理编码时,地理编码的点可能会标注为街道地址、城市(芝加哥)、所在州(伊利诺伊州)或国家/地区(美国)。这些对地理编码器来说都是地址。反向地理编码器会返回所有这些结果。

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

以下是上述查询可能会返回的地址列表示例:

results[0].formatted_address: "277 Bedford Ave, Brooklyn, NY 11211, USA"
results[1].formatted_address: "Grand St/Bedford Av, Brooklyn, NY 11211, USA"
results[2].formatted_address: "Williamsburg, Brooklyn, NY, USA"
results[3].formatted_address: "Brooklyn, NY, USA"
results[4].formatted_address: "New York, NY, USA"
results[5].formatted_address: "Brooklyn, NY 11211, USA"
results[6].formatted_address: "Kings County, NY, USA"
results[7].formatted_address: "New York-Northern New Jersey-Long Island, NY-NJ-PA, USA"
results[8].formatted_address: "New York Metropolitan Area, USA"
results[9].formatted_address: "New York, USA"

地址会按匹配度从高到低的顺序返回。通常,最确切的地址就是最明显的结果,如此例中所示。请注意,我们会返回不同类型的地址,从最具体的街道地址到较为宽泛的政治实体(例如街区、市、县、州/省/自治区/直辖市等)。如果您想要匹配更广泛的地址,可能要检查 results[].types 字段。

注意:反向地理编码并不能做到完全精确。地理编码器会尝试在一定的偏差范围内查找最接近的可寻址位置。

检索地点 ID 的地址

提供 placeId 以查找给定地点 ID 的地址。地点 ID 是可与其他 Google API 搭配使用的唯一标识符。例如,您可以提供 Roads API 返回的 placeId,以获取贴靠点的地址。如需详细了解地点 ID,请参阅地点 ID 概览

当您提供 placeId 时,请求不能包含以下任何字段:

  • address
  • latLng
  • location
  • componentRestrictions

以下示例接受地点 ID,查找相应的地址,并将地图中心设为该位置。系统还会显示一个信息窗口,其中显示相关地点的格式化地址:

TypeScript

// Initialize the map.
function initMap(): void {
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      zoom: 8,
      center: { lat: 40.72, lng: -73.96 },
    }
  );
  const geocoder = new google.maps.Geocoder();
  const infowindow = new google.maps.InfoWindow();

  (document.getElementById("submit") as HTMLElement).addEventListener(
    "click",
    () => {
      geocodePlaceId(geocoder, map, infowindow);
    }
  );
}

// This function is called when the user clicks the UI button requesting
// a geocode of a place ID.
function geocodePlaceId(
  geocoder: google.maps.Geocoder,
  map: google.maps.Map,
  infowindow: google.maps.InfoWindow
) {
  const placeId = (document.getElementById("place-id") as HTMLInputElement)
    .value;

  geocoder
    .geocode({ placeId: placeId })
    .then(({ results }) => {
      if (results[0]) {
        map.setZoom(11);
        map.setCenter(results[0].geometry.location);

        const marker = new google.maps.Marker({
          map,
          position: results[0].geometry.location,
        });

        infowindow.setContent(results[0].formatted_address);
        infowindow.open(map, marker);
      } else {
        window.alert("No results found");
      }
    })
    .catch((e) => window.alert("Geocoder failed due to: " + e));
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;

JavaScript

// Initialize the map.
function initMap() {
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 8,
    center: { lat: 40.72, lng: -73.96 },
  });
  const geocoder = new google.maps.Geocoder();
  const infowindow = new google.maps.InfoWindow();

  document.getElementById("submit").addEventListener("click", () => {
    geocodePlaceId(geocoder, map, infowindow);
  });
}

// This function is called when the user clicks the UI button requesting
// a geocode of a place ID.
function geocodePlaceId(geocoder, map, infowindow) {
  const placeId = document.getElementById("place-id").value;

  geocoder
    .geocode({ placeId: placeId })
    .then(({ results }) => {
      if (results[0]) {
        map.setZoom(11);
        map.setCenter(results[0].geometry.location);

        const marker = new google.maps.Marker({
          map,
          position: results[0].geometry.location,
        });

        infowindow.setContent(results[0].formatted_address);
        infowindow.open(map, marker);
      } else {
        window.alert("No results found");
      }
    })
    .catch((e) => window.alert("Geocoder failed due to: " + e));
}

window.initMap = initMap;
查看示例

试用示例