Dịch vụ độ 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ó trong API JavaScript của Maps. 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 các dịch vụ của Google Maps, Ứng dụng Java, Ứng dụng Python và Ứng dụng Go cho các dịch vụ của 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ụ Độ 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ả vị trí độ sâu dưới đáy đại dương (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ề 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 nhằm lấy 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 về độ 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. Dịch vụ này nhận các yêu cầu về độ 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, ứng dụng định vị di động hoặ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 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 rồi nhấp vào Mở.
3. Trong danh sách API trên Trang tổng quan, hãy tìm Elevation API.
4. Nếu bạn thấy API đó trong danh sách, thì bạn không cần làm gì thêm. Nếu API không có trong danh sách, hãy bật API đó:
   1. Ở đầu trang, hãy chọn BẬT API để hiển thị thẻ 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 Elevation API, sau đó 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, Elevation API sẽ xuất hiện trong danh sách API trên Trang tổng quan.

Giá và chính sách

Giá

Để tìm hiểu về chính sách giá và mức sử dụng cho dịch vụ Độ cao JavaScript, hãy xem phần 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 thủ các chính sách được mô tả cho Elevation API.

Yêu cầu nâng cao quyền

Việc truy cập vào dịch vụ Độ cao là 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 truyền một phương thức gọi lại để thực thi 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ả. Xin lưu ý rằng dịch vụ Độ cao 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:

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

Mỗi phương thức này cũng phải truyề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 nâng cao vị trí

Một đối tượng chữ 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 lấy một mảng LatLng.

Bạn có thể truyền số lượng toạ độ bất kỳ trong một mảng, miễn là không vượt quá hạn 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 về độ cao của đường dẫn được lấy mẫu

Một đối tượng chữ PathElevationRequest chứa các trường sau:

{
  path[]: LatLng,
  samples: Number
}

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

• path (bắt buộc) xác định một đường dẫn trên trái đất để trả về dữ liệu độ cao. Tham số path xác định một tập hợp gồm hai hoặc nhiều cặp {vĩ độ,kinh độ} được sắp xếp theo thứ tự 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ố đ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 nhau theo thứ tự dọc theo đường dẫn.

Giống như các yêu cầu theo vị trí, tham số path chỉ định một tập hợp các 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ó thứ tự. Thay vì trả về dữ liệu độ cao tại các đỉnh, các yêu cầu về đường dẫn sẽ đượ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 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 một đối tượng ElevationStatus.

Trạng thái nâng cao

Mỗi yêu cầu về độ cao sẽ trả về một mã ElevationStatus trong hàm callback của yêu cầu đó. 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ụ có định dạng không chính xác
• 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 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ó 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ả về độ cao

Nếu 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. Các đối tượng này chứa những phần tử sau:

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

Ví dụ về độ cao

Đoạn mã sau đây chuyển một lượt nhấp trên bản đồ thành một yêu cầu về độ cao bằng cách sử dụng đối tượng LocationElevationRequest:

TypeScript

async function init(): Promise<void> {
    const [{ InfoWindow }, { ElevationService }] = await Promise.all([
        google.maps.importLibrary('maps'),
        google.maps.importLibrary('elevation'),
    ]);

    const mapElement = document.querySelector('gmp-map')!;
    const innerMap = mapElement.innerMap;

    const elevator = new ElevationService();
    const infowindow = new InfoWindow();

    infowindow.open(innerMap);

    // Add a listener for the click event. Display the elevation for the LatLng of
    // the click inside the infowindow.
    innerMap.addListener('click', (event: google.maps.MapMouseEvent) => {
        displayLocationElevation(event.latLng!, elevator, infowindow, innerMap);
    });
}

function displayLocationElevation(
    location: google.maps.LatLng,
    elevator: google.maps.ElevationService,
    infowindow: google.maps.InfoWindow,
    map: google.maps.Map
) {
    // Format numeric values to two decimal places
    const formatter = new Intl.NumberFormat(undefined, {
        maximumFractionDigits: 2,
    });

    // Initiate the location request
    elevator
        .getElevationForLocations({
            locations: [location],
        })
        .then(({ results }) => {
            if (results[0]) {
                const { elevation, location: resultLocation } = results[0];
                infowindow.setPosition(resultLocation);
                infowindow.setContent(
                    `The elevation at ${String(resultLocation)} <br>is ${formatter.format(elevation)} meters.`
                );
            } else {
                infowindow.setPosition(location);
                infowindow.setContent('No results found');
            }

            infowindow.open(map);
        })
        .catch((e: unknown) => {
            infowindow.setContent(
                `Elevation service failed due to: ${String(e)}`
            );
        });
}

void init();
index.ts

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

JavaScript

async function init() {
    const [{ InfoWindow }, { ElevationService }] = await Promise.all([
        google.maps.importLibrary('maps'),
        google.maps.importLibrary('elevation'),
    ]);

    const mapElement = document.querySelector('gmp-map');
    const innerMap = mapElement.innerMap;

    const elevator = new ElevationService();
    const infowindow = new InfoWindow();

    infowindow.open(innerMap);

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

function displayLocationElevation(location, elevator, infowindow, map) {
    // Format numeric values to two decimal places
    const formatter = new Intl.NumberFormat(undefined, {
        maximumFractionDigits: 2,
    });

    // Initiate the location request
    elevator
        .getElevationForLocations({
            locations: [location],
        })
        .then(({ results }) => {
            if (results[0]) {
                const { elevation, location: resultLocation } = results[0];
                infowindow.setPosition(resultLocation);
                infowindow.setContent(
                    `The elevation at ${String(resultLocation)} <br>is ${formatter.format(elevation)} meters.`
                );
            } else {
                infowindow.setPosition(location);
                infowindow.setContent('No results found');
            }

            infowindow.open(map);
        })
        .catch((e) => {
            infowindow.setContent(
                `Elevation service failed due to: ${String(e)}`
            );
        });
}

void init();
index.js

Xem ví dụ

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

Lưu ý: Đọ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 }, // 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

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

Xem ví dụ