Dịch vụ nâng cao

Tổng quan

Dịch vụ Độ cao cung cấp dữ liệu độ cao cho các vị trí trên bề mặt trái đất, bao gồm cả vị trí độ sâu trên đáy đại dương (trả về giá trị âm). Trong những trường hợp mà Google không sở hữu số liệu đo độ cao chính xác ở vị trí bạn yêu cầu, thì dịch vụ sẽ nội suy và trả về một giá trị trung bình bằng cách sử dụng bốn 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 vị trí trên trái đất để xác định độ cao . Ngoài ra, bạn có thể yêu cầu dữ liệu độ cao được lấy mẫu dọc theo đường dẫn, cho phép bạn tính toán sự thay đổi độ cao cách đều nhau dọc theo các tuyến đường. Đối tượng ElevationService giao tiếp với Dịch vụ độ cao của API Google Maps nhận độ cao yêu cầu và trả về dữ liệu về độ cao.

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

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 Raise API được bật trong Google Cloud Console, trong cùng một dự án bạn thiết lập cho API Maps JavaScript.

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

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

Giá và chính sách

Giá

Kể từ ngày 16 tháng 7 năm 2018, gói giá mới trả theo mức dùng đã bắt đầu có hiệu lực. cho Bản đồ, Tuyến đường và Địa điểm. Để tìm hiểu thêm về mức giá và mức sử dụng mới các giới hạn đối với việc sử dụng dịch vụ Độ cao JavaScript, hãy xem Mức 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 các chính sách nêu trên cho API Độ cao.

Yêu cầu độ cao

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ủ. Vì lý do đó, bạn cần truyền một lệnh gọi lại để thực thi sau khi hoàn tất yêu cầu. Chiến dịch này sẽ xử lý(các) kết quả. Lưu ý rằng Dịch vụ độ cao trả về mã trạng thái (ElevationStatus) và một mảng các tham số riêng biệt Đối tượng ElevationResult.

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

• Yêu cầu các vị trí riêng biệt bằng cách sử dụng getElevationForLocations(), được chuyển danh sách một hoặc nhiều vị trí bằng cách sử dụng Đối tượng LocationElevationRequest.
• Yêu cầu về độ cao trên một loạt các điểm được kết nối dọc theo một đường dẫn bằng phương thức getElevationAlongPath(), Giá trị này được truyền một tập hợp các đỉnh đường dẫn có 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 truyền một thông số cho biết bạn muốn đưa bao nhiêu mẫu theo đường dẫn đó.

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

Yêu cầu nâng cao vị trí

Đối tượng LocationElevationRequest bằng chữ chứa trường sau:

{
  locations[]: LatLng
}

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

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

Yêu cầu độ cao đường dẫn được lấy mẫu

Đối tượng PathElevationRequest bằng chữ 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 một đường dẫn trên trái đất để trả về dữ liệu độ cao. path tham số xác định một tập hợp gồm hai hoặc nhiều thứ tự {latitude,longitude} 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 mẫu các điểm dọc theo một đường dẫn để trả về dữ liệu độ cao. Chiến lược phát hành đĩa đơn Tham số samples chia path đã cho thành một tập hợp có thứ tự các điểm cách đều nhau dọc theo đường đi.

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

Phản hồi độ cao

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

Trạng thái cao độ

Mỗi yêu cầu độ 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ụ là không đúng định dạng
• OVER_QUERY_LIMIT cho biết người yêu cầu đã vượt quá hạn mức
• REQUEST_DENIED cho biết dịch vụ chưa hoàn tất yêu cầu, có thể là do một thông 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 bạn có thành công không bằng cách kiểm tra lệnh này mã trạng thái cho OK.

Kết quả đo độ cao

Sau khi thành công, đối số results của lệnh gọi lại hàm sẽ chứa một tập hợp các đối tượng ElevationResult. Các đối tượng này chứa các phần tử sau:

• Phần tử location (chứa LatLng đối tượng) của vị trí mà dữ liệu độ cao đang được tính toán. Ghi chú đố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 điểm dữ liệu mà từ đó độ cao được nội suy, tính bằng mét. Chiến dịch này sẽ bị thiếu nếu không xác định được độ phân giải. Lưu ý rằng dữ liệu độ cao trở nên tương đối hơn (giá trị resolution lớn hơn) khi có nhiều điểm được truyền. Để có được độ cao chính xác nhất cho một điểm, nó nên được truy vấn một cách độc lập.

Ví dụ về độ cao

Mã sau đây chuyển một cú nhấp chuột trên bản đồ thành độ cao yêu cầu bằng đối tượng LocationElevationRequest:

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;
index.ts

function initMap() {
  const map = new google.maps.Map(document.getElementById("map"), {
    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, 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;
index.js

Ví dụ sau đây dựng một hình nhiều đường dựa vào một tập hợp toạ độ và hiển thị dữ liệu độ cao dọc theo đường dẫn đó bằng cách sử dụng API Trực quan hoá của Google. (Bạn phải tải API này bằng Loader.) Yêu cầu về độ cao được xây dựng bằng cách sử dụng PathElevationRequest:

// 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;
index.ts

// 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 }, // 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"), {
    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;
index.js