地理编码服务

概览

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

反向地理编码是将地理位置坐标转换为直观易懂的地址的过程（请参阅反向地理编码[地址查询]）。

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

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

使用入门

在使用 Maps JavaScript API 中的地理编码服务之前，请先前往 Google Cloud 控制台，确保已针对您为 Maps JavaScript API 设置的同一项目启用了 Geocoding API。

若要查看已启用的 API 列表，请按以下步骤操作：

  1. 前往 Google Cloud 控制台。
  2. 点击选择项目按钮，选择您为 Maps JavaScript API 设置的同一项目，然后点击打开。
  3. 在信息中心上的 API 列表中，查找 Geocoding API。
  4. 如果您在列表中看到该 API，就说明一切就绪。如果其中未列出该 API，请执行以下操作将其启用：
    1. 在页面顶部，选择启用 API 以显示库标签页。或者，您也可以从左侧菜单中选择库。
    2. 搜索 Geocoding API，然后从结果列表中选择它。
    3. 选择启用。该过程完成后，Geocoding API 即会显示在信息中心上的 API 列表中。

定价和政策

价格

如需了解 JavaScript 地理编码服务的定价和使用政策，请参阅 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 - LatLngBounds，可在此区域内进一步自定义调整地理编码结果。bounds 参数只会影响但不会完全限制地理编码器中的结果。如需了解详情，请参阅下文的视口自定义调整。
  • componentRestrictions - 用于将结果限制在特定区域内。如需了解详情，请参阅下文的组成部分过滤。
  • region - 地区代码，已指定为双字符（非数字）Unicode 地区子标记。大多数情况下，这些标记会直接映射到熟悉的 ccTLD（“顶级域名”）双字符值。region 参数只会影响但不会完全限制地理编码器中的结果。如需了解详情，请参阅下文的地区代码自定义调整。
  • extraComputations - 此参数的唯一允许值为 ADDRESS_DESCRIPTORS。如需了解详情，请参阅 地址描述符。
  • fulfillOnZeroResults - 在响应中针对 ZERO_RESULT 状态执行 promise。这可能很有用，因为即使没有任何地理编码结果，系统可能仍会返回其他响应级字段。如需了解详情，请参阅 在没有结果时执行执行方式。

地理编码响应

地理编码服务需要一个在检索到地理编码器的结果后执行的回调方法。此回调应传递两个参数，用于存储 results 和 status 代码（按该顺序）。

地理编码结果

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[] 是一个数组，表示返回结果的地址类型。此数组包含零个或多个标记，用于标识结果中所返回的地图项的类型。例如，“Chicago”的地理编码会返回“locality”，表示“Chicago”是一个城市；同时返回“political”，表示它是一个政治实体。如需了解详情，请参阅下文的地址类型和地址组成部分类型。
  • 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 的数量因所请求的地址而异，对于同一个地址，数量也可能会随着时间推移而发生变化。组成部分在数组中的位置可能发生变化。组成部分的类型也可能发生变化。后续响应中可能缺少特定组成部分。

    如需了解详情，请参阅下文的地址类型和地址组成部分类型。

  • partial_match 表示地理编码器无法返回与原始请求完全匹配的结果，尽管它能够匹配所请求地址的一部分内容。建议您检查一下原始请求中是否存在拼写错误和/或地址不完整的情况。

    部分匹配的最常见原因是请求中所传递的市行政区内不存在相关街道地址。当请求与同一市行政区中的两个或更多位置相匹配时，也可能会返回部分匹配。例如，无论是 Henry Street 还是 Henrietta Street，“Hillpar St, Bristol, UK”都会返回部分匹配。请注意，如果请求中包含拼写错误的地址组成部分，地理编码服务可能会推荐备选地址。通过这种方式触发的建议也将标记为部分匹配。

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

  • geometry 包含以下信息：

    • location 包含经过地理编码的纬度和经度值。请注意，我们会以 LatLng 对象（而非某种格式的字符串）的形式返回此位置。
    • location_type 会存储有关指定位置的其他数据。目前支持以下值：
      • ROOFTOP 表示返回的结果反映了一个精确的地理编码。
      • RANGE_INTERPOLATED 表示返回的结果反映了插值到两个精确点（例如交叉路口）之间的大概位置（通常是在道路上）。当某个街道地址的 rooftop 地理编码不可用时，通常会返回插值结果。
      • GEOMETRIC_CENTER 表示返回的结果是多段线（例如街道）或多边形（例如区域）等结果的几何图形中心。
      • APPROXIMATE 表示返回的结果是大概位置。

    • viewport 存储返回结果的推荐视口。
    • bounds（选择性返回）存储可完全包含返回结果的 LatLngBounds。请注意，这些边界可能与推荐的视口不一致（例如，旧金山包含法拉隆群岛，理论上后者是前者的一部分，但不应该在视口中返回）。

地理编码器将使用浏览器的首选语言设置或在加载 API JavaScript 时使用 language 参数指定的语言返回这些地址（如需了解详情，请参阅本地化）。

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

GeocoderResult 中的 types[] 数组表示地址类型。GeocoderAddressComponent 中也可能会返回 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 分别表示公交车、火车或公共交通车站的位置。

状态代码

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

  • "OK" 表示未出现任何错误；已成功解析地址，并且至少返回了一个地理编码。
  • "ZERO_RESULTS" 表示地理编码成功，但未返回任何结果。如果向地理编码器传递了不存在的 address，就可能会发生这种情况。
  • "OVER_QUERY_LIMIT" 表示您超出了配额。
  • "REQUEST_DENIED" 表示您的请求已遭拒。不允许网页使用地理编码器。
  • "INVALID_REQUEST" 通常表示缺少查询参数（address、components 或 latlng）。
  • "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”的地理编码通常会返回芝加哥的“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”表示“Great Britain”）。

使用 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"
}

将 region 字段设置为 'es'（西班牙）后，“Toledo”的地理编码将返回西班牙的城市：

{
  "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 参数按 country 和 postalCode 进行过滤：

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);
  }
});
}

在无结果时执行执行

对于反向地理编码，默认情况下，status=ZERO_RESULTS 会破坏 promise。不过，在这种情况下，系统可能仍会填充 plus_code 和 address_descriptor 的其他响应级字段。如果为 fulfillOnZeroResults 参数提供 true，则不会破坏 promise，并且可以通过 promise 访问这些额外字段（如果存在）。

以下是南极洲纬度/经度的这种行为示例。 即使没有反向地理编码结果，如果我们设置了 fulfillOnZeroResults=true，仍然可以在 Promise 中输出 Plus Code。

    function addressDescriptorReverseGeocoding() {
      var latlng = new google.maps.LatLng(-75.290330, 38.653861);
      geocoder
        .geocode({
          'location': latlng,
          'fulfillOnZeroResults': true,
        })
        .then((response) => {
          console.log(response.plus_code);
        })
        .catch((error) => {
          window.alert(`Error`);
        });
    }

地址描述符

地址描述符包含其他信息，可帮助使用地标和区域描述地点。如需探索此功能，请查看地址描述符演示。

您可以使用 extraComputations 参数启用地址描述符。在地理编码请求、反向地理编码请求或地点地理编码请求中添加 extra_computations=ADDRESS_DESCRIPTORS，以便在响应中接收地址描述符。

地点地理编码示例

以下查询包含德里某个地点的地址。

function addressDescriptorPlaceIdLookup() {
  geocoder.geocode({
    'placeId': 'ChIJyxAX8Bj9DDkRgBfAnBYa66Q',
    'extraComputations': ['ADDRESS_DESCRIPTORS']
    }, function(results, status) {
    if (status == 'OK') {
      console.log(results[0].address_descriptor);
    } else {
      window.alert('Geocode was not successful for the following reason: ' + status);
    }
  });
}

反向地理编码示例

以下查询包含德里某个地点的纬度/经度值。

    function addressDescriptorReverseGeocoding() {
      var latlng = new google.maps.LatLng(28.640964,77.235875);
      geocoder
        .geocode({
          'location': latlng,
          'extraComputations': ["ADDRESS_DESCRIPTORS"],
        })
        .then((response) => {
          console.log(response.address_descriptor);
        })
        .catch((error) => {
          window.alert(`Error`);
        });
    }

地址描述符示例

address_descriptor 示例如下所示。

  {
    "address_descriptor" : {
       "areas" : [
          {
             "containment" : "OUTSKIRTS",
             "display_name" : {
                "language_code" : "en",
                "text" : "Turkman Gate"
             },
             "place_id" : "ChIJ_7LLvyb9DDkRMKKxP9YyXgs"
          },
          {
             "containment" : "OUTSKIRTS",
             "display_name" : {
                "language_code" : "en",
                "text" : "Chandni Chowk"
             },
             "place_id" : "ChIJWcXciBr9DDkRUb4dCDykTwI"
          },
          {
             "containment" : "NEAR",
             "display_name" : {
                "language_code" : "en",
                "text" : "Katar Ganj"
             },
             "place_id" : "ChIJH3cWUyH9DDkRaw-9CjvcRvY"
          }
       ],
       "landmarks" : [
          {
             "display_name" : {
                "language_code" : "en",
                "text" : "Delite Cinema"
             },
             "straight_line_distance_meters" : 29.9306755065918,
             "place_id" : "ChIJLfiYDCT9DDkROoEa7NdupUM",
             "travel_distance_meters" : 418.7794799804688,
             "spatial_relationship" : "ACROSS_THE_ROAD",
             "types" : [ "establishment", "movie_theater", "point_of_interest" ]
          },
          {
             "display_name" : {
                "language_code" : "en",
                "text" : "YES Bank"
             },
             "straight_line_distance_meters" : 66.83731079101562,
             "place_id" : "ChIJFYHM3yb9DDkRRKGkZl2mpSQ",
             "travel_distance_meters" : 489.0340270996094,
             "spatial_relationship" : "DOWN_THE_ROAD",
             "types" : [ "bank", "establishment", "finance", "point_of_interest" ]
          },
          {
             "display_name" : {
                "language_code" : "en",
                "text" : "UCO Bank"
             },
             "straight_line_distance_meters" : 25.38849639892578,
             "place_id" : "ChIJ-c6_wCb9DDkRjIk1LeqRtGM",
             "travel_distance_meters" : 403.2246398925781,
             "spatial_relationship" : "ACROSS_THE_ROAD",
             "types" : [ "atm", "bank", "establishment", "finance", "point_of_interest" ]
          },
          {
             "display_name" : {
                "language_code" : "en",
                "text" : "Delhi By Cycle Meeting Point"
             },
             "straight_line_distance_meters" : 44.02867126464844,
             "place_id" : "ChIJNxVfkSb9DDkRJD22l-eGFdM",
             "travel_distance_meters" : 97.41281890869141,
             "spatial_relationship" : "AROUND_THE_CORNER",
             "types" : [
                "establishment",
                "point_of_interest",
                "tourist_attraction",
                "travel_agency"
             ]
          },
          {
             "display_name" : {
                "language_code" : "en",
                "text" : "Axis Bank Branch"
             },
             "straight_line_distance_meters" : 102.3495178222656,
             "place_id" : "ChIJr3uaDCT9DDkR8roHTVSn1x4",
             "travel_distance_meters" : 330.8566284179688,
             "spatial_relationship" : "DOWN_THE_ROAD",
             "types" : [ "bank", "establishment", "finance", "point_of_interest" ]
          }
       ]
    }
  }

每个 address_descriptor 对象中都有两个数组：landmarks 和 areas。landmarks 数组最多包含 5 条结果，这些结果会按相关性进行排名，其中会考虑与请求坐标的距离、地标的普及程度和可见度。每个地标结果都包含以下值：

  • place_id 是地图注点结果的地点 ID。请参阅地点 ID 概览。
  • display_name 是地标的显示名称，包含 language_code 和 text。
  • straight_line_distance_meters 是输入坐标与地图注点结果之间的点对点距离（以米为单位）。
  • travel_distance_meters 是输入坐标与地图注点结果之间通过道路网格（忽略道路限制）行驶的距离（以米为单位）。
  • spatial_relationship 是输入坐标与地标结果之间的估算关系：
    • 如果不符合上述任何情况，则默认关系为 "NEAR"。
    • 如果输入坐标包含在与地标相关联的结构的边界内，则为 "WITHIN"。
    • 如果输入坐标与地标或地标的接入点直接相邻，则为 "BESIDE"。
    • 如果输入坐标与相应路线另一侧的地标正好相反，则返回 "ACROSS_THE_ROAD"。
    • 如果输入坐标与地标位于同一路线上，但不是 "BESIDES" 或 "ACROSS_THE_ROAD"，则为 "DOWN_THE_ROAD"。
    • 如果输入坐标与地标位于垂直路线上（仅限于单个转弯），则为 "AROUND_THE_CORNER"。
    • 如果输入坐标在空间上靠近地标，但距离其接入点较远，则为 "BEHIND"。
  • types 是地标的地点类型。

areas 对象最多包含 3 个回答，并且仅限于代表小区域的地点，例如社区、子区域和大型建筑群。包含请求坐标的区域会先列出，并按面积从小到大排序。每个 areas 结果都包含以下值：

  • place_id 是相应区域结果的地点 ID。请参阅地点 ID 概览。
  • display_name 是相应区域的显示名称，包含 language_code 和 text。
  • containment 是输入坐标与区域结果之间的估算包含关系：
    • 如果不符合上述任何情况，则默认关系为 "NEAR"。
    • 如果输入坐标接近区域中心，则为 "WITHIN"。
    • 当输入坐标接近相应区域边缘时，返回 "OUTSKIRTS"。

地址描述符覆盖率

地址描述符在印度的 Google Analytics 中采用印度语。在印度使用地址描述符无需额外付费，其使用费用已包含在现有的地理编码（印度）必备 SKU 中。

反馈

此功能在所有地区均可使用。该功能已在印度正式发布，在所有其他地区处于正式发布前的实验性版本发布阶段。我们期待收到您的反馈：

反向地理编码（地址查找）

“地理编码”这一术语通常是指将直观易懂的地址转换为地图上某个位置的过程。与之相反，将地图上的某个位置转换为直观易懂的地址的过程称为“反向地理编码”。

在 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
    .ge>ocode({ 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(&q>uot;No results found");
      }
    })
    .catch((e) = window.alert("Geocoder failed due to: &q>uot; + e));
}

declare global {
  inte
rface Wi
ndow {
    initMap: () = void;
  }
}
window.initMap = initMap;index.ts

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(&qu>ot;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({ lo>cation: 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 res>ults found");
      }
    })
    .catch((e) = window.alert("Geocod
er faile
d due to: " + e));
}

window.initMap = initMap;index.js
查看示例

试用示例

请注意，在上一个示例中，我们通过选择 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({ place>Id: 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 res>ults found");
      }
    })
    .catch((e) = window.alert("Geocoder failed due to: " + e))>;
}

declare global {
  interface Wind
ow {
   
 initMap: () = void;
  }
}
window.initMap = initMap;index.ts

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").addEventLi>stener("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({ place>Id: 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 res>ults found");
      }
    })
    .catch((e) = window.alert("Geocod
er faile
d due to: " + e));
}

window.initMap = initMap;index.js
查看示例

试用示例