一切就绪!

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

激活 Google Maps JavaScript API

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

  1. 创建或选择项目
  2. 激活 Google Maps JavaScript API 及相关服务
  3. 创建相应密钥
继续

地理编码服务

概览

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

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

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

入门指南

在 Google Maps JavaScript API 中使用地理编码服务之前,首先要确保在为 Google Maps JavaScript API 设置的同一项目的 Google API Console 中启用 Google Maps Geocoding API。

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

  1. 转至 Google API Console
  2. 点击 Select a project 按钮,然后选择为 Google Maps JavaScript API 设置的同一项目并点击 Open
  3. Dashboard 上的 API 列表中,寻找 Google Maps Geocoding API
  4. 如果在列表中看到该 API,则大功告成。如果列出该 API,请执行以下操作将其启用:
    1. 在页面顶部,选择 ENABLE API 以显示 Library 标签。也可从左侧菜单中选择 Library
    2. 搜索 Google Maps Geocoding API,然后从结果列表中选择它。
    3. 选择 ENABLE。流程完成时,Google Maps Geocoding API 即会出现在 Dashboard 上的 API 列表中。

使用限额和政策

配额

对于地理编码服务,具有以下使用限额:

搭配标准计划使用地理编码服务

  • 每天 2,500 次免费请求,按客户端与服务器端查询次数之和计算; 启用计费可获得更高每日配额,按 0.50 美元/1000 次额外请求计费,每日上限为 100,000 次请求。
  • 每秒 50 次请求,按客户端与服务器端查询次数之和计算。

搭配高级计划使用地理编码服务

  • 100,000 个请求的每日免费共享配额(每 24 小时);根据每年购买的 Maps API 额度提供的额外请求。
  • 每个项目每秒 不受限制 次客户端请求。请注意,服务器端 API 有每秒 50 次请求的限制。

无论有多少位用户共享同一项目,均以用户会话为单位施加速率限制。

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

政策

必须按照所介绍的适用于 Google Maps 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 是唯一一个可以与其他 Google API 结合使用的标识符。例如,您可以使用由 Google Maps Roads API 返回的 placeId 来获取某个拍摄点的地址。如需了解有关地点 ID 的详细信息,请参阅地点 ID 概览。如果您传递一个 placeId,则地理编码器会执行反向地理编码。如需了解详细信息,请参阅反向地理编码

可选参数

  • bounds:在其中可以使地理编码结果更显著地发生偏向的 LatLngBoundsbounds 参数只会影响,而不会完全限制地理编码器中的结果。(如需了解详细信息,请参阅下面的视口偏向。)
  • componentRestrictions:用于将结果限制在某个特定区域。(如需了解详细信息,请参阅下面的组成部分过滤。)
  • region:以 IANA 语言 region 子标记指定的区域代码。大多数情况下,这些标记会直接映射到您熟悉的 ccTLD(“顶级域”)双字符值。region 参数只会影响,而不会完全限制地理编码器中的结果。(如需了解详细信息,请参阅下面的区域代码偏向。)

地理编码响应

地理编码服务需要一个在检索到地理编码器的结果后立即执行的回调方法。此回调应传递两个参数,用于存储 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[]:是一个表示所返回结果的类型 的数组。此数组包含一组标记(可能为零个或多个),用于标识结果中所返回特征的类型。例如,“芝加哥”的地理编码返回“locality”,这表明“芝加哥”是一个城市,并且还返回“political”,这表明它是一个政治实体。
  • formatted_address:是一个包含此位置可人工读取的地址的字符串。通常此地址相当于“邮政地址”,有时会因国家/地区而异。(请注意,由于许可限制,某些国家(如英国)不允许发布真实的邮政地址。)此地址通常由一个或多个地址组成部分组成。例如,地址“111 8th Avenue, New York, NY”包含以下地址组成部分:“111 8th Avenue”(街道地址)、“New York”(城市)和“NY”(美国的一个州)。这些地址组成部分阐述如下。(如需了解有关类型的详细信息,请参阅下面的类型。)
  • address_components[] 是包含独立的地址组成部分的数组,如上所述。
  • partial_match 表示虽然地理编码器能够匹配所请求的地址的一部分,但它未能返回原始请求的精确匹配项。您不妨检查一下原始请求中是否有拼写错误和/或地址不完整的情况。

    对于请求中所传递的行政区划内不存在的街道地址,最常发生部分匹配的情况。当请求与同一行政区划中的两个或更多位置相匹配时,也可能会返回部分匹配。例如,“21 Henr 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:表示返回的结果反映了两个精确点(例如交叉路口)之间用内插法计算得到的近似值(通常在道路上)。当某个街道地址的 rooftop 地理编码不可用时,通常会返回内插值结果。
      • GEOMETRIC_CENTER:表示返回的结果是某个位置(如多段线[例如街道]或多边形[地区])的几何中心。
      • APPROXIMATE:表示返回的结果是近似值。

    • viewport:用于存储返回结果的推荐视口。
    • bounds(可选返回):用于存储可完全包含返回结果的 LatLngBounds。请注意,这些边界可能与推荐的视口不一致。(例如,旧金山包含费拉隆岛,理论上它是这个城市的一部分,但不应该在视口中返回。)

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

地址组成部分类型

返回结果中的 types[] 数组表示地址类型。这些类型还可能包含在 address_components[] 数组中返回,以表示特殊地址组成部分的类型。地理编码器的地址可能具有多个类型;这些类型可能会被视为“标记”。例如,许多城市都标有 politicallocality 类型。

HTTP 地理编码器支持并返回以下类型:

  • street_address 表示精确的街道地址。
  • route:表示已命名的路线(例如“US 101”)
  • intersection:表示主要交叉路口,通常是两条主要道路的交叉路口
  • political:表示政治实体。通常,这种类型表示某个民政管理部门的多边形
  • country:表示国家政治实体,通常是由地理编码器返回的最高级别类型
  • administrative_area_level_1:表示国家/地区级别以下的一级行政实体。在美国,这种行政级别就是州。并非所有国家都设有这类行政级别
  • administrative_area_level_2:表示国家/地区级别以下的二级行政实体。在美国,这种行政级别就是县。并非所有国家都设有这类行政级别
  • administrative_area_level_3:表示国家/地区级别以下的三级行政实体。此类型表示较小的行政区划单位。并非所有国家都设有这类行政级别
  • administrative_area_level_4:表示国家/地区级别以下的四级行政实体。此类型表示较小的行政区划单位。并非所有国家都设有这类行政级别
  • administrative_area_level_5:表示国家/地区级别以下的五级行政实体。此类型表示较小的行政区划单位。并非所有国家都设有这类行政级别
  • colloquial_area:表示实体的常用替代名称
  • locality 表示合并的城市或城镇政治实体。
  • sublocality:表示 locality 以下的一级行政实体。某些位置可能会收到其他类型之一:从 sublocality_level_1sublocality_level_5。每个 sublocality 级别都是一个行政实体。数字越大,表示的地理区域越小
  • neighborhood:表示已命名的街区
  • premise 表示已命名的位置,通常是具有常见名称的一栋或一群建筑物
  • subpremise:表示指定位置以下的一级实体,通常是同名建筑群中的单个建筑物
  • postal_code 表示邮政编码,用于国内的地址邮寄。
  • natural_feature:表示著名的自然景观
  • airport:表示机场
  • park:表示已命名的公园。

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

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

  • post_box 表示特定的邮政信箱。
  • street_number 表示确切的门牌号码。
  • floor:表示某个建筑物地址的楼层
  • room 表示某个建筑物地址的房间。

状态代码

status 代码可能返回下列值之一:

  • "OK" 表示未出现任何错误;已成功解析地址,并且至少返回了一个地理编码。
  • "ZERO_RESULTS" 表示地理编码成功,但未返回任何结果。如果向地理编码器传递了一个不存在 address,就可能会发生这种情况。
  • "OVER_QUERY_LIMIT" 表示您已超出配额。
  • "REQUEST_DENIED" 表示系统已拒绝您的请求。
  • "INVALID_REQUEST" 一般表示缺少查询(addresscomponentslatlng)。
  • "UNKNOWN_ERROR" 表示由于服务器发生错误,因此无法处理该请求。如果您重试一次,请求可能会成功

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

  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>

查看示例 (geocoding-simple.html)

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

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

Geocoder 支持直接进行反向地理编码。在 location 参数中提供以逗号分隔的纬度/经度对,而不是提供文本 address。或者,提供 placeId,以查找对应于给定的地点 ID 的地址。

根据位置进行反向地理编码

下例对纬度/经度值进行地理编码,并将该位置置于在地图的中心,而且会打开一个信息窗口,其中显示格式化的地址。我们返回第二种结果,第二种结果不如第一种结果那么具体(在此例中,为一个邻近地区的名称):

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

  document.getElementById('submit').addEventListener('click', function() {
    geocodeLatLng(geocoder, map, infowindow);
  });
}

function geocodeLatLng(geocoder, map, infowindow) {
  var input = document.getElementById('latlng').value;
  var latlngStr = input.split(',', 2);
  var latlng = {lat: parseFloat(latlngStr[0]), lng: parseFloat(latlngStr[1])};
  geocoder.geocode({'location': latlng}, function(results, status) {
    if (status === 'OK') {
      if (results[1]) {
        map.setZoom(11);
        var marker = new google.maps.Marker({
          position: latlng,
          map: map
        });
        infowindow.setContent(results[1].formatted_address);
        infowindow.open(map, marker);
      } else {
        window.alert('No results found');
      }
    } else {
      window.alert('Geocoder failed due to: ' + status);
    }
  });
}
<div id="floating-panel">
  <input id="latlng" type="text" value="40.714224,-73.961452">
  <input id="submit" type="button" value="Reverse Geocode">
</div>
<div id="map"></div>
/* Always set the map height explicitly to define the size of the div
 * element that contains the map. */
#map {
  height: 100%;
}
/* Optional: Makes the sample page fill the window. */
html, body {
  height: 100%;
  margin: 0;
  padding: 0;
}
#floating-panel {
  position: absolute;
  top: 10px;
  left: 25%;
  z-index: 5;
  background-color: #fff;
  padding: 5px;
  border: 1px solid #999;
  text-align: center;
  font-family: 'Roboto','sans-serif';
  line-height: 30px;
  padding-left: 10px;
}
#floating-panel {
  position: absolute;
  top: 5px;
  left: 50%;
  margin-left: -180px;
  width: 350px;
  z-index: 5;
  background-color: #fff;
  padding: 5px;
  border: 1px solid #999;
}
#latlng {
  width: 225px;
}
 <!-- Replace the value of the key parameter with your own API key. -->
<script async defer
src="https://maps.googleapis.com/maps/api/js?key=AIzaSyCkUOdZ5y7hMm0yrcCQoCvLwzdM6M8s5qk&callback=initMap">
</script>
function initMap() {
  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 8,
    center: {lat: 40.731, lng: -73.997}
  });
  var geocoder = new google.maps.Geocoder;
  var infowindow = new google.maps.InfoWindow;

  document.getElementById('submit').addEventListener('click', function() {
    geocodeLatLng(geocoder, map, infowindow);
  });
}

function geocodeLatLng(geocoder, map, infowindow) {
  var input = document.getElementById('latlng').value;
  var latlngStr = input.split(',', 2);
  var latlng = {lat: parseFloat(latlngStr[0]), lng: parseFloat(latlngStr[1])};
  geocoder.geocode({'location': latlng}, function(results, status) {
    if (status === 'OK') {
      if (results[1]) {
        map.setZoom(11);
        var marker = new google.maps.Marker({
          position: latlng,
          map: map
        });
        infowindow.setContent(results[1].formatted_address);
        infowindow.open(map, marker);
      } else {
        window.alert('No results found');
      }
    } else {
      window.alert('Geocoder failed due to: ' + status);
    }
  });
}

查看示例 (geocoding-reverse.html)

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

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

由上一查询返回的完整地址列表如下所示。

results[0].formatted_address: "275-291 Bedford Ave, Brooklyn, NY 11211, USA",
results[1].formatted_address: "Williamsburg, NY, USA",
results[2].formatted_address: "New York 11211, USA",
results[3].formatted_address: "Kings, New York, USA",
results[4].formatted_address: "Brooklyn, New York, USA",
results[5].formatted_address: "New York, New York, USA",
results[6].formatted_address: "New York, USA",
results[7].formatted_address: "United States"

返回的地址按最佳匹配度至最低匹配度顺序排列。通常,正如本例中所示,最准确的地址在结果中摆在最突出的位置。请注意,我们会返回不同类型的地址,从最具体的街道地址到不那么具体的政治实体,如街区、市、县、州等。如果您希望匹配更宽泛的地址,您可能想要检查 results[].types 字段。

注:反向地理编码并不是一门精确科学。地理编码器将尝试在某一误差限度范围内查找最接近的可寻址位置。

根据地点 ID 进行反向地理编码

下例接受一个地点 ID、查找相应的地址并将该位置置于地图的中心。此外,它还打开一个信息窗口,其中显示相关地点的格式化地址:

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

  document.getElementById('submit').addEventListener('click', function() {
    geocodePlaceId(geocoder, map, infowindow);
  });
}

// This function is called when the user clicks the UI button requesting
// a reverse geocode.
function geocodePlaceId(geocoder, map, infowindow) {
  var placeId = document.getElementById('place-id').value;
  geocoder.geocode({'placeId': placeId}, function(results, status) {
    if (status === 'OK') {
      if (results[0]) {
        map.setZoom(11);
        map.setCenter(results[0].geometry.location);
        var marker = new google.maps.Marker({
          map: map,
          position: results[0].geometry.location
        });
        infowindow.setContent(results[0].formatted_address);
        infowindow.open(map, marker);
      } else {
        window.alert('No results found');
      }
    } else {
      window.alert('Geocoder failed due to: ' + status);
    }
  });
}
<div id="floating-panel">
  <!-- Supply a default place ID for a place in Brooklyn, New York. -->
  <input id="place-id" type="text" value="ChIJd8BlQ2BZwokRAFUEcm_qrcA">
  <input id="submit" type="button" value="Reverse Geocode by Place ID">
</div>
<div id="map"></div>
/* Always set the map height explicitly to define the size of the div
 * element that contains the map. */
#map {
  height: 100%;
}
/* Optional: Makes the sample page fill the window. */
html, body {
  height: 100%;
  margin: 0;
  padding: 0;
}
#floating-panel {
  position: absolute;
  top: 10px;
  left: 25%;
  z-index: 5;
  background-color: #fff;
  padding: 5px;
  border: 1px solid #999;
  text-align: center;
  font-family: 'Roboto','sans-serif';
  line-height: 30px;
  padding-left: 10px;
}
#floating-panel {
  width: 440px;
}
#place-id {
  width: 250px;
}
 <!-- Replace the value of the key parameter with your own API key. -->
<script async defer
src="https://maps.googleapis.com/maps/api/js?key=AIzaSyCkUOdZ5y7hMm0yrcCQoCvLwzdM6M8s5qk&callback=initMap">
</script>
// Initialize the map.
function initMap() {
  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 8,
    center: {lat: 40.72, lng: -73.96}
  });
  var geocoder = new google.maps.Geocoder;
  var infowindow = new google.maps.InfoWindow;

  document.getElementById('submit').addEventListener('click', function() {
    geocodePlaceId(geocoder, map, infowindow);
  });
}

// This function is called when the user clicks the UI button requesting
// a reverse geocode.
function geocodePlaceId(geocoder, map, infowindow) {
  var placeId = document.getElementById('place-id').value;
  geocoder.geocode({'placeId': placeId}, function(results, status) {
    if (status === 'OK') {
      if (results[0]) {
        map.setZoom(11);
        map.setCenter(results[0].geometry.location);
        var marker = new google.maps.Marker({
          map: map,
          position: results[0].geometry.location
        });
        infowindow.setContent(results[0].formatted_address);
        infowindow.open(map, marker);
      } else {
        window.alert('No results found');
      }
    } else {
      window.alert('Geocoder failed due to: ' + status);
    }
  });
}

查看示例 (geocoding-place-id.html)

视口偏向

此外,您还可以指示让地理编码服务倾向于使用某个给定视口(表示为边框)中的结果。要实现此目的,您可以通过在 GeocoderRequest 对象字面量中设置 bounds 参数来定义此视口的边界。请注意,偏向只是倾向于使用边界以内的结果;如果在这些边界之外存在更相关的结果,也可能会将这些结果包括在内。

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

{
  "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 参数会使得此地理编码返回位于该位置的名为“温内特卡”的邻近地区:

{
  "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 参数将地理编码服务设置为返回偏向特定区域的结果。此参数采用一个以 IANA 语言 region 子标记指定的区域代码。大多数情况下,这些标记会直接映射到熟悉的 ccTLD(“顶级域”)双字符值,例如“co.uk”中的“uk”。某些情况下,region 标记也支持 ISO-3166-1 代码,该代码有时会与 ccTLD 值有所不同(例如,“GB”表示“Great Britain”)。

可以针对主要 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 参数指定此限制。过滤器包括一个或多个:routelocalityadministrativeAreapostalCodecountry。只有符合所有过滤器的结果才会被返回。过滤器值支持与其他地理编码请求相同的用于拼写校正和部分匹配的方法。

下例函数演示如何通过使用 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);
  }
});
}

发送以下问题的反馈:

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