海拔服务

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

概览

海拔服务提供地球表面各个位置的海拔数据,包括海底深处位置(返回负值)。如果 Google 无法精确到您请求的确切地点的海拔高度测量结果,该服务会插入并传回四个最近地点的平均值。

ElevationService 对象为您提供了一个简单的查询接口,供您查询地球上各个位置的海拔数据。此外,您还可以请求沿路径的采样海拔数据,以便计算沿路径的等距海拔变化。ElevationService 对象会与 Google Maps API 海拔服务进行通信,该服务将接收海拔请求并返回海拔数据。

借助海拔服务,您可以开发徒步和骑行应用、移动定位应用或低分辨率测量应用。

开始使用

在 Maps JavaScript API 中使用海拔服务之前,首先确保在 Google Cloud Console 中为您为 Maps JavaScript API 设置的同一项目启用了 Elevation API。

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

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

价格和政策

价格

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

速率限制

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

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

基于会话的速率限制可防止将客户端服务用于批量请求。相反,如果您想计算已知静态位置的海拔,请使用 Elevation API 网络服务

政策

使用海拔服务时必须遵守适用于 Elevation API 的政策

海拔请求

Google Maps API 需要调用外部服务器,因此对海拔服务的访问是异步的。因此,您需要传递一个回调方法,以便在请求完成后执行。此回调方法将会对结果进行处理。请注意,海拔服务会返回一个状态代码 (ElevationStatus) 和一个由单独的 ElevationResult 对象组成的数组。

ElevationService 可处理两种类型的请求:

  • 使用 getElevationForLocations() 方法请求获取单独的离散位置,该方法使用 LocationElevationRequest 对象传递一个或多个位置的列表。
  • 使用 getElevationAlongPath() 方法请求路径沿线的一系列连接点上的海拔,这将在 PathElevationRequest 对象内传递一组经过排序的路径顶点。请求沿路径的海拔时,您还必须传递一个参数,以指示您希望沿该路径抽取多少个样本。

上述每个方法还必须传递一个回调方法来处理返回的 ElevationResultElevationStatus 对象。

位置海拔请求

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

{
  locations[]: LatLng
}

locations(必需)用于定义地球上要返回海拔数据的位置。此参数接受 LatLng 数组。

您可以在数组中传递任意数量的坐标,只要不超过服务配额即可。 请注意,在传递多个坐标时,任何返回数据的精度可能低于请求单个坐标的数据时的分辨率。

抽样路径海拔请求

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

{
  path[]: LatLng,
  samples: Number
}

这些字段的含义如下:

  • path(必需)定义地球上要返回海拔数据的路径。path 参数使用包含两个或更多 LatLng 对象的数组来定义一组包含两个或更多个有序的 {纬度,经度} 对。
  • samples(必需)用于指定要返回其海拔数据的路径上的采样点数量。samples 参数用于将指定的 path 分为一组沿路径的有序等距点。

与位置请求一样,path 参数会指定一组纬度和经度值。不过,与位置请求不同的是,path 会指定一组有序顶点。路径请求不是在顶点处返回海拔数据,而是沿路径的长度进行采样,其中每个样本都彼此等距(包括端点)。

海拔响应

对于每个有效的请求,海拔服务都会向已定义的回调返回一组 ElevationResult 对象和一个 ElevationStatus 对象。

海拔状态

每个海拔请求都会在其回调函数中返回一个 ElevationStatus 代码。此 status 代码将包含以下某个值:

  • OK,表示服务请求已成功
  • INVALID_REQUEST,表示服务请求格式不正确
  • OVER_QUERY_LIMIT 表示请求者超出了配额
  • REQUEST_DENIED 表示服务未完成请求,可能是因为参数无效
  • UNKNOWN_ERROR,表示出现未知错误

您应通过检查 OK 的此状态代码来检查回调是否成功。

海拔结果

成功后,回调函数的 results 参数将包含一组 ElevationResult 对象。这些对象包含以下元素:

  • 将为其计算海拔数据的位置的 location 元素(包含 LatLng 对象)。请注意,对于路径请求,location 元素集将包含沿路径的采样点。
  • elevation 元素,用于指示营业地点的高度(以米为单位)。
  • resolution 值,用于表示计算海拔时所用数据点之间的最大距离,以米为单位。如果分辨率未知,则不会显示此属性。请注意,传递多个点时,海拔数据会更粗略(resolution 值更大)。若要获得最精确的海拔高度值,应单独查询。

海拔示例

以下代码使用 LocationElevationRequest 对象将地图上的点击转换为海拔请求:

TypeScript

function initMap(): void {
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      zoom: 8,
      center: { lat: 63.333, lng: -150.5 }, // Denali.
      mapTypeId: "terrain",
    }
  );
  const elevator = new google.maps.ElevationService();
  const infowindow = new google.maps.InfoWindow({});

  infowindow.open(map);

  // Add a listener for the click event. Display the elevation for the LatLng of
  // the click inside the infowindow.
  map.addListener("click", (event) => {
    displayLocationElevation(event.latLng, elevator, infowindow);
  });
}

function displayLocationElevation(
  location: google.maps.LatLng,
  elevator: google.maps.ElevationService,
  infowindow: google.maps.InfoWindow
) {
  // Initiate the location request
  elevator
    .getElevationForLocations({
      locations: [location],
    })
    .then(({ results }) => {
      infowindow.setPosition(location);

      // Retrieve the first result
      if (results[0]) {
        // Open the infowindow indicating the elevation at the clicked position.
        infowindow.setContent(
          "The elevation at this point <br>is " +
            results[0].elevation +
            " meters."
        );
      } else {
        infowindow.setContent("No results found");
      }
    })
    .catch((e) =>
      infowindow.setContent("Elevation service 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: 63.333, lng: -150.5 },
    mapTypeId: "terrain",
  });
  const elevator = new google.maps.ElevationService();
  const infowindow = new google.maps.InfoWindow({});

  infowindow.open(map);
  // Add a listener for the click event. Display the elevation for the LatLng of
  // the click inside the infowindow.
  map.addListener("click", (event) => {
    displayLocationElevation(event.latLng, elevator, infowindow);
  });
}

function displayLocationElevation(location, elevator, infowindow) {
  // Initiate the location request
  elevator
    .getElevationForLocations({
      locations: [location],
    })
    .then(({ results }) => {
      infowindow.setPosition(location);
      // Retrieve the first result
      if (results[0]) {
        // Open the infowindow indicating the elevation at the clicked position.
        infowindow.setContent(
          "The elevation at this point <br>is " +
            results[0].elevation +
            " meters."
        );
      } else {
        infowindow.setContent("No results found");
      }
    })
    .catch((e) =>
      infowindow.setContent("Elevation service failed due to: " + e)
    );
}

window.initMap = initMap;
查看示例

试用示例

下例使用一组 Google 坐标构造一条多段线,并显示沿着该路径的海拔数据。(您必须使用 Google 通用加载程序加载此 API。)海拔请求使用 PathElevationRequest 构造:

TypeScript

// Load the Visualization API and the columnchart package.
// @ts-ignore TODO update to newest visualization library
google.load("visualization", "1", { packages: ["columnchart"] });

function initMap(): void {
  // The following path marks a path from Mt. Whitney, the highest point in the
  // continental United States to Badwater, Death Valley, the lowest point.
  const path = [
    { lat: 36.579, lng: -118.292 }, // Mt. Whitney
    { lat: 36.606, lng: -118.0638 }, // Lone Pine
    { lat: 36.433, lng: -117.951 }, // Owens Lake
    { lat: 36.588, lng: -116.943 }, // Beatty Junction
    { lat: 36.34, lng: -117.468 }, // Panama Mint Springs
    { lat: 36.24, lng: -116.832 },
  ]; // Badwater, Death Valley

  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      zoom: 8,
      center: path[1],
      mapTypeId: "terrain",
    }
  );

  // Create an ElevationService.
  const elevator = new google.maps.ElevationService();

  // Draw the path, using the Visualization API and the Elevation service.
  displayPathElevation(path, elevator, map);
}

function displayPathElevation(
  path: google.maps.LatLngLiteral[],
  elevator: google.maps.ElevationService,
  map: google.maps.Map
) {
  // Display a polyline of the elevation path.
  new google.maps.Polyline({
    path: path,
    strokeColor: "#0000CC",
    strokeOpacity: 0.4,
    map: map,
  });

  // Create a PathElevationRequest object using this array.
  // Ask for 256 samples along that path.
  // Initiate the path request.
  elevator
    .getElevationAlongPath({
      path: path,
      samples: 256,
    })
    .then(plotElevation)
    .catch((e) => {
      const chartDiv = document.getElementById(
        "elevation_chart"
      ) as HTMLElement;

      // Show the error code inside the chartDiv.
      chartDiv.innerHTML = "Cannot show elevation: request failed because " + e;
    });
}

// Takes an array of ElevationResult objects, draws the path on the map
// and plots the elevation profile on a Visualization API ColumnChart.
function plotElevation({ results }: google.maps.PathElevationResponse) {
  const chartDiv = document.getElementById("elevation_chart") as HTMLElement;

  // Create a new chart in the elevation_chart DIV.
  const chart = new google.visualization.ColumnChart(chartDiv);

  // Extract the data from which to populate the chart.
  // Because the samples are equidistant, the 'Sample'
  // column here does double duty as distance along the
  // X axis.
  const data = new google.visualization.DataTable();

  data.addColumn("string", "Sample");
  data.addColumn("number", "Elevation");

  for (let i = 0; i < results.length; i++) {
    data.addRow(["", results[i].elevation]);
  }

  // Draw the chart using the data within its DIV.
  chart.draw(data, {
    height: 150,
    legend: "none",
    // @ts-ignore TODO update to newest visualization library
    titleY: "Elevation (m)",
  });
}

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

JavaScript

// Load the Visualization API and the columnchart package.
// @ts-ignore TODO update to newest visualization library
google.load("visualization", "1", { packages: ["columnchart"] });

function initMap() {
  // The following path marks a path from Mt. Whitney, the highest point in the
  // continental United States to Badwater, Death Valley, the lowest point.
  const path = [
    { lat: 36.579, lng: -118.292 },
    { lat: 36.606, lng: -118.0638 },
    { lat: 36.433, lng: -117.951 },
    { lat: 36.588, lng: -116.943 },
    { lat: 36.34, lng: -117.468 },
    { lat: 36.24, lng: -116.832 },
  ]; // Badwater, Death Valley
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 8,
    center: path[1],
    mapTypeId: "terrain",
  });
  // Create an ElevationService.
  const elevator = new google.maps.ElevationService();

  // Draw the path, using the Visualization API and the Elevation service.
  displayPathElevation(path, elevator, map);
}

function displayPathElevation(path, elevator, map) {
  // Display a polyline of the elevation path.
  new google.maps.Polyline({
    path: path,
    strokeColor: "#0000CC",
    strokeOpacity: 0.4,
    map: map,
  });
  // Create a PathElevationRequest object using this array.
  // Ask for 256 samples along that path.
  // Initiate the path request.
  elevator
    .getElevationAlongPath({
      path: path,
      samples: 256,
    })
    .then(plotElevation)
    .catch((e) => {
      const chartDiv = document.getElementById("elevation_chart");

      // Show the error code inside the chartDiv.
      chartDiv.innerHTML = "Cannot show elevation: request failed because " + e;
    });
}

// Takes an array of ElevationResult objects, draws the path on the map
// and plots the elevation profile on a Visualization API ColumnChart.
function plotElevation({ results }) {
  const chartDiv = document.getElementById("elevation_chart");
  // Create a new chart in the elevation_chart DIV.
  const chart = new google.visualization.ColumnChart(chartDiv);
  // Extract the data from which to populate the chart.
  // Because the samples are equidistant, the 'Sample'
  // column here does double duty as distance along the
  // X axis.
  const data = new google.visualization.DataTable();

  data.addColumn("string", "Sample");
  data.addColumn("number", "Elevation");

  for (let i = 0; i < results.length; i++) {
    data.addRow(["", results[i].elevation]);
  }

  // Draw the chart using the data within its DIV.
  chart.draw(data, {
    height: 150,
    legend: "none",
    // @ts-ignore TODO update to newest visualization library
    titleY: "Elevation (m)",
  });
}

window.initMap = initMap;
查看示例

试用示例