Dịch vụ nâng cao

Lưu ý: Thư viện phía máy chủ

Trang này mô tả dịch vụ phía máy khách có sẵn với API Maps JavaScript. Nếu bạn muốn làm việc với các dịch vụ web của Google Maps trên máy chủ của mình, hãy xem Ứng dụng Node.js cho Dịch vụ của Google Maps. Trang tại đường liên kết đó cũng giới thiệu về Ứng dụng Java, Ứng dụng Python và Go Client cho Dịch vụ Google Maps.

Tổng quan

Ngoài ra, hãy xem Tài liệu tham khảo API JavaScript của Maps: Độ cao

Dịch vụ nâng 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ả các vị trí độ sâu dưới đáy đại dương (các vị trí này sẽ trả về giá trị âm). Trong những trường hợp Google không có số đ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 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 các vị trí trên trái đất cho dữ liệu độ cao. Ngoài ra, bạn có thể yêu cầu dữ liệu độ cao được 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 độ 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 API Google Maps để nhận yêu cầu nâng 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 điện thoại 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 JavaScript của Maps, 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 JavaScript của Maps.

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

1. Chuyển đến 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 API JavaScript của Maps và nhấp vào Mở.
3. Từ danh sách API trên Trang tổng quan, hãy tìm API độ cao.
4. Nếu thấy API trong danh sách thì bạn đã đặt xong. Nếu API không được liệt kê, hãy bật API đó:
   1. Ở đầu trang, hãy chọn ENABLE API (Bật API) để hiển thị thẻ Library. Ngoài ra, trên trình đơn bên trái, hãy chọn Library (Thư viện).
   2. Tìm API Elevation, sau đó chọn API này từ danh sách kết quả.
   3. Chọn BẬT. Khi quá trình hoàn tất, API Elevation sẽ xuất hiện trong danh sách các API trên Trang tổng quan.

Giá và chính sách

Giá

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

Chính sách

Sử dụng dịch vụ Độ cao phải phù hợp với chính sách được mô tả cho API Độ cao.

Yêu cầu độ cao

Truy cập dịch vụ Độ cao là không đồng bộ, vì API Google Maps cần thực hiện cuộc gọi đến máy chủ bên ngoài. Vì lý do đó, bạn cần chuyển phương thức callback để gọi lại 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ột 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:

• Các yêu cầu về 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 được truyề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 nâng 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(). 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 nâng cao 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 mà bạn muốn lấy theo đường dẫn đó.

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

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

Đối tượng LocationElevationRequest chứa 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 độ cao. Tham số này sẽ nhận một mảng LatLng.

Bạn có thể chuyển số lượng tọa độ 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 chuyể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 đường dẫn được lấy 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 một đườ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 gồm hai cặp {latitude,kinh độ} trở lên được sắp xếp bằng cách sử dụng một mảng gồm hai đối tượng LatLng trở lên.
• samples (bắt buộc) chỉ định số lượng điểm mẫu dọc theo một đường dẫn để trả về dữ liệu độ cao. Tham số samples chia path đã cho thành một tập hợp các điểm cách đều theo thứ tự trên đường dẫn.

Giống như với yêu cầu vị trí, tham số path chỉ định một tập hợp giá trị vĩ độ và kinh độ. Tuy nhiên, không giống như yêu cầu 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, yêu cầu đường dẫn được lấy mẫu dọc theo chiều dài của đường dẫn, trong đó mỗi mẫu cách đều với nhau (bao gồm cả 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ề 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 những 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 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 lệnh gọi lại của mình thành công bằng cách kiểm tra mã trạng thái này cho OK.

Kết quả độ cao

Khi thành công, đối số results của hàm gọi lại 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 đối tượng LatLng) của vị trí đang được tính toán dữ liệu độ cao. 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 biết độ phân giải. Lưu ý rằng dữ liệu độ cao sẽ thô hơn (giá trị resolution lớn hơn) khi nhiều điểm được truyền. Để nhận được giá trị độ cao chính xác nhất cho một điểm, giá trị độ cao phải được truy vấn độc lập.

Ví dụ về độ cao

Mã sau đây chuyển một lượt nhấp trên bản đồ thành một yêu cầu nâng cao 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;
index.ts

Lưu ý: Hãy đọc hướng dẫn về cách sử dụng TypeScript và Google Maps.

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

Lưu ý: JavaScript được biên dịch từ đoạn mã TypeScript.

Xem ví dụ

Dùng thử mẫu

JSFiddle.net CodeSandbox.io Google Cloud Shell

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

Lưu ý: Hãy đọc hướng dẫn về cách sử dụng TypeScript và Google Maps.

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

Lưu ý: JavaScript được biên dịch từ đoạn mã TypeScript.

Xem ví dụ

Dùng thử mẫu

JSFiddle.net CodeSandbox.io Google Cloud Shell