Dịch vụ nâng cao

Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.

Tổng quan

Dịch vụ Độ cao cung cấp dữ liệu về độ cao cho các vị trí trên bề mặt trái đất, bao gồm cả các vị trí độ sâu dưới đáy đại dương (trả về các giá trị âm). Trong những trường hợp mà Google không có kết quả đo độ cao chính xác tại vị trí chính xác mà bạn yêu cầu, dịch vụ sẽ nội suy và trả về một giá trị trung bình bằng cách sử dụng 4 vị trí gần nhất.

Đối tượng ElevationService cung cấp cho bạn một giao diện đơn giản để truy vấn các vị trí trên trái đất về dữ liệu độ cao. Ngoài ra, bạn có thể yêu cầu dữ liệu độ cao lấy mẫu dọc theo các đường dẫn, cho phép bạn tính toán các thay đổi về độ cao tương đương dọc theo các tuyến đường. Đối tượng ElevationService giao tiếp với Dịch vụ độ cao API Google Maps. Dịch vụ này nhận yêu cầu độ cao và trả về dữ liệu độ cao.

Với dịch vụ Độ cao, bạn có thể phát triển các ứng dụng đi bộ đường dài và đi xe đạp, các ứng dụng định vị trên thiết bị di động hoặc các ứng dụng khảo sát có độ phân giải thấp.

Bắt đầu

Trước khi sử dụng dịch vụ Độ cao trong API Maps JavaScript, trước tiên hãy đảm bảo rằng API độ cao được bật trong Google Cloud Console, trong cùng một dự án mà bạn đã thiết lập cho API Maps JavaScript.

Cách xem danh sách các API đã bật:

  1. Truy cập vào Google Cloud Console.
  2. Nhấp vào nút Select a project (Chọn một dự án), sau đó chọn cùng một dự án mà bạn đã thiết lập cho Maps JavaScript API và nhấp vào Open (Mở).
  3. Trong danh sách API trên Dashboard (Trang tổng quan), hãy tìm Elevation API.
  4. Nếu bạn thấy API này trong danh sách thì bạn đã hoàn tất. Nếu API không có trong danh sách, hãy bật API:
    1. Ở đầu trang, hãy chọn ENABLE API (BẬT API) để hiển thị thẻ Library (Thư viện). Ngoài ra, trên trình đơn bên trái, hãy chọn Thư viện.
    2. Tìm kiếm Elevation API, sau đó chọn API này trong danh sách kết quả.
    3. Chọn ENABLE (BẬT). Khi quá trình này kết thúc, API Elevation sẽ xuất hiện trong danh sách các API trên Dashboard (Trang tổng quan).

Mức giá và các chính sách

Giá

Kể từ ngày 16 tháng 7 năm 2018, gói giá trả theo mức giá mới sẽ có hiệu lực đối với Maps, Tuyến đường và Địa điểm. Để tìm hiểu thêm về giới hạn sử dụng và giá cả mới đối với việc bạn sử dụng dịch vụ Độ cao JavaScript, hãy xem Sử dụng và thanh toán cho API Độ cao.

Chính sách

Việc sử dụng dịch vụ Độ cao phải tuân theo chính sách được mô tả cho API Độ cao.

Yêu cầu độ cao

Việc truy cập dịch vụ Độ cao không đồng bộ vì API Google Maps cần thực hiện lệnh gọi đến một máy chủ bên ngoài. Vì lý do đó, bạn cần chuyển phương thức lệnh gọi lại để thực thi sau khi hoàn tất yêu cầu. Phương thức gọi lại này sẽ xử lý(các) kết quả. Lưu ý rằng dịch vụ Độ cao sẽ trả về mã trạng thái (ElevationStatus) và một mảng các đối tượng ElevationResult riêng biệt.

ElevationService xử lý hai loại yêu cầu:

  • Yêu cầu đối với các vị trí riêng biệt, riêng biệt bằng cách sử dụng phương thức getElevationForLocations(), phương thức này sẽ được truyền danh sách của một hoặc nhiều vị trí bằng cách sử dụng đối tượng LocationElevationRequest.
  • Yêu cầu độ cao trên một loạt điểm nối với nhau qua một đường dẫn bằng cách sử dụng phương thức getElevationAlongPath(), phương thức này được truyền một tập hợp các đỉnh đường dẫn theo thứ tự trong một đối tượng PathElevationRequest. Khi yêu cầu độ cao dọc theo đường dẫn, bạn cũng phải chuyển một thông số cho biết số lượng mẫu bạn muốn đi theo đường dẫn đó.

Mỗi phương thức này cũng phải truyền một phương thức lệnh gọi lại để xử lý các đối tượng ElevationResultElevationStatus được trả về.

Yêu cầu độ cao cho vị trí

Đối tượng LocationElevationRequest chứa giá trị cố định trong trường sau:

{
  locations[]: LatLng
}

locations (bắt buộc) xác định(các) vị trí trên trái đất để trả về dữ liệu về độ cao. Thông số này sẽ lấy một mảng LatLng.

Bạn có thể chuyển số lượng toạ độ bất kỳ trong một mảng, miễn là bạn không vượt quá định mức dịch vụ. Xin lưu ý rằng khi truyền nhiều toạ độ, độ chính xác của mọi dữ liệu được trả về có thể có độ phân giải thấp hơn so với khi yêu cầu dữ liệu cho một toạ độ.

Yêu cầu độ cao của đường dẫn mẫu

Đối tượng PathElevationRequest chứa các trường sau:

{
  path[]: LatLng,
  samples: Number
}

Các trường này được giải thích bên dưới:

  • path (bắt buộc) xác định đường dẫn trên trái đất để trả về dữ liệu độ cao. Thông số path xác định một tập hợp hai hoặc nhiều cặp {lpurl,longitude} được sắp xếp bằng cách sử dụng một mảng gồm hai hoặc nhiều đối tượng LatLng.
  • samples (bắt buộc) chỉ định số lượng điểm mẫu dọc theo một đường dẫn mà sẽ trả về dữ liệu độ cao. Tham số samples chia path đã cho thành một tập hợp các điểm tương đương theo thứ tự dọc theo đường dẫn.

Giống như các yêu cầu về vị trí, tham số path chỉ định một nhóm giá trị vĩ độ và kinh độ. Tuy nhiên, không giống như yêu cầu về vị trí, path chỉ định một tập hợp các đỉnh được sắp xếp theo thứ tự. Thay vì trả về dữ liệu độ cao ở các đỉnh, các yêu cầu đường dẫn được lấy mẫu dọc theo chiều dài của đường dẫn, nơi mỗi mẫu đều có khoảng cách bằng nhau (bao gồm cả các điểm cuối).

Phản hồi về độ cao

Đối với mỗi yêu cầu hợp lệ, dịch vụ Độ cao sẽ trả về lệnh gọi lại đã xác định, một tập hợp các đối tượng ElevationResult cùng với đối tượng ElevationStatus.

Trạng thái độ cao

Mỗi yêu cầu nâng cao sẽ trả về một mã ElevationStatus trong hàm callback. Mã status này sẽ chứa một trong các giá trị sau:

  • OK cho biết yêu cầu dịch vụ đã thành công
  • INVALID_REQUEST cho biết yêu cầu dịch vụ không đúng định dạng
  • OVER_QUERY_LIMIT cho biết rằng người yêu cầu đã vượt quá hạn mức
  • REQUEST_DENIED cho biết dịch vụ không hoàn tất yêu cầu, có thể là do một tham số không hợp lệ
  • UNKNOWN_ERROR cho biết lỗi không xác định

Bạn nên kiểm tra xem lệnh gọi lại của mình có thành công hay không bằng cách kiểm tra mã trạng thái này cho OK.

Kết quả nâng cao

Khi thành công, đối số results của hàm callback sẽ chứa một tập hợp các đối tượng ElevationResult. Những đối tượng này chứa các phần tử sau:

  • Một phần tử location (chứa các đối tượng LatLng) của vị trí đang tính toán dữ liệu độ cao. Hãy lưu ý rằng đối với các yêu cầu đường dẫn, tập hợp các phần tử location sẽ chứa các điểm được lấy mẫu dọc theo đường dẫn.
  • Phần tử elevation cho biết độ cao của vị trí tính bằng mét.
  • Giá trị resolution, cho biết khoảng cách tối đa giữa các điểm dữ liệu mà từ đó độ cao được nội suy, tính bằng mét. Thuộc tính này sẽ bị thiếu nếu bạn không xác định được độ phân giải. Lưu ý rằng dữ liệu độ cao sẽ trở nên thô hơn (giá trị resolution lớn hơn) khi nhiều điểm được truyền. Để có được giá trị độ chính xác cao nhất cho một điểm, giá trị đó cần được truy vấn một cách độc lập.

Ví dụ về độ cao

Mã sau đây sẽ chuyển đổi một lượt nhấp vào bản đồ thành một yêu cầu nâng (elevation) bằng cách sử dụng đối tượng 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;
Xem ví dụ

Thử mẫu

Ví dụ sau đây sẽ tạo một polyline cho một bộ toạ độ và hiển thị dữ liệu độ cao dọc theo đường dẫn đó bằng Google Visual API. (Bạn phải tải API này bằng Trình tải chung của Google.) Yêu cầu độ cao được xây dựng bằng cách sử dụng 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;
Xem ví dụ

Thử mẫu