บริการลิฟต์

หมายเหตุ: ไลบรารีฝั่งเซิร์ฟเวอร์

หน้านี้อธิบายบริการฝั่งไคลเอ็นต์ที่ใช้ได้กับ Maps JavaScript API หากต้องการทํางานกับบริการเว็บ Google Maps บนเซิร์ฟเวอร์ โปรดดูไคลเอ็นต์ Node.js สําหรับบริการ Google Maps นอกจากนี้ หน้าเว็บที่ลิงก์ดังกล่าวยังแสดงไคลเอ็นต์ Java, ไคลเอ็นต์ Python และไคลเอ็นต์ Go สําหรับบริการ Google Maps ด้วย

ภาพรวม

โปรดดูข้อมูลอ้างอิงของ Maps JavaScript API ด้วย: ระดับความสูง

บริการระดับความสูงให้ข้อมูลระดับความสูง ของพื้นโลก รวมถึงตําแหน่งความลึกของก้นมหาสมุทร (ซึ่งจะแสดงผลค่าลบ) ในกรณีที่ Google ไม่มีการวัดระดับความสูงที่แน่นอน ณ ตําแหน่งที่แน่นอนที่คุณขอ บริการจะประเมินและแสดงผลค่าเฉลี่ยโดยใช้ตําแหน่งที่ใกล้ที่สุด 4 แห่ง

ออบเจ็กต์ ElevationService มีอินเทอร์เฟซที่ใช้งานง่ายสําหรับค้นหาตําแหน่งบนโลกเพื่อดูข้อมูลระดับความสูง นอกจากนี้ คุณอาจขอข้อมูลระดับความสูงที่สุ่มตัวอย่างตลอดเส้นทาง ซึ่งจะช่วยให้คุณคํานวณการเปลี่ยนแปลงระดับความสูงที่เท่ากันระหว่างเส้นทางได้ ออบเจ็กต์ ElevationService สื่อสารกับบริการระดับความสูงของ Google Maps API ซึ่งรับคําขอระดับความสูงและแสดงผลข้อมูลระดับความสูง

ด้วยบริการยกระดับ คุณสามารถพัฒนาแอปพลิเคชันเดินป่าและปั่นจักรยาน แอปพลิเคชันจัดตําแหน่งบนอุปกรณ์เคลื่อนที่ หรือแอปพลิเคชันสํารวจความละเอียดต่ํา

การเริ่มต้นใช้งาน

ก่อนใช้บริการ Elevation ใน Maps JavaScript API โปรดตรวจสอบว่าได้เปิดใช้ Elevation API ใน Google Cloud Console แล้วในโปรเจ็กต์เดียวกับที่ตั้งค่าไว้สําหรับ Maps JavaScript API

วิธีดูรายการ API ที่เปิดใช้

1. ไปที่ Google Cloud Console
2. คลิกปุ่มเลือกโปรเจ็กต์ แล้วเลือกโปรเจ็กต์เดียวกับที่ตั้งค่าไว้สําหรับ Maps JavaScript API แล้วคลิกเปิด
3. ค้นหา Elevation API จากรายการ API ในหน้าแดชบอร์ด
4. หากเห็น API ในรายการ แสดงว่าทุกอย่างพร้อมแล้ว หาก ไม่ แสดงอยู่ใน API ให้เปิดใช้
   1. ที่ด้านบนของหน้า ให้เลือกเปิดใช้ API เพื่อแสดงแท็บไลบรารี หรือเลือกคลังจากเมนูด้านซ้าย
   2. ค้นหา Elevation API แล้วเลือกจากรายการผลลัพธ์
   3. เลือกเปิดใช้ เมื่อเสร็จสิ้นกระบวนการแล้ว Elevation API จะปรากฏในรายการ API ในหน้าแดชบอร์ด

ราคาและนโยบาย

ราคา

แพ็กเกจราคาแบบจ่ายเมื่อใช้จะมีผลตั้งแต่วันที่ 16 กรกฎาคม 2018 สําหรับ Maps, เส้นทาง และสถานที่ หากต้องการดูข้อมูลเพิ่มเติมเกี่ยวกับขีดจํากัดราคาและการใช้งานใหม่สําหรับการใช้บริการ JavaScript Elevation โปรดดูการใช้งานและการเรียกเก็บเงินสําหรับ Elevation API

นโยบาย

การใช้บริการ Elevation ต้องเป็นไปตามนโยบายที่อธิบายเกี่ยวกับ Elevation API

คําขอระดับความสูง

การเข้าถึงบริการระดับความสูงจะไม่พร้อมกัน เนื่องจาก Google Maps API ต้องเรียกใช้ไปยังเซิร์ฟเวอร์ภายนอก ด้วยเหตุนี้ คุณจึงต้องส่งเมธอด callback เพื่อดําเนินการตามคําขอให้เสร็จสมบูรณ์ วิธีเรียกกลับนี้ควรประมวลผลผลการค้นหา โปรดทราบว่าบริการระดับความสูงจะแสดงรหัสสถานะ (ElevationStatus) และอาร์เรย์ของออบเจ็กต์ ElevationResult แยกต่างหาก

ElevationService รองรับคําขอ 2 ประเภทดังนี้

• คําขอตําแหน่งแยกต่างหากแบบแยกกันโดยใช้เมธอด getElevationForLocations() ซึ่งส่งรายการตําแหน่งอย่างน้อย 1 รายการโดยใช้ออบเจ็กต์ LocationElevationRequest
• คําขอระดับความสูงของชุดจุดที่เชื่อมต่อตลอดเส้นทางโดยใช้เมธอด getElevationAlongPath() ซึ่งส่งต่อชุดของจุดตัดที่เรียงลําดับภายในออบเจ็กต์ PathElevationRequest เมื่อขอระดับความสูงระหว่างเส้นทาง คุณต้องส่งพารามิเตอร์ที่ระบุจํานวนตัวอย่างที่คุณต้องการไปตามเส้นทางนั้นด้วย

แต่ละวิธีต้องส่งผ่านเมธอด callback เพื่อจัดการออบเจ็กต์ ElevationResult และ ElevationStatus ที่แสดงผลด้วย

คําขอระดับความสูงของสถานที่ตั้ง

ลิเทอรัลของออบเจ็กต์ LocationElevationRequest มีช่องต่อไปนี้

{
  locations[]: LatLng
}

locations (จําเป็น) ระบุตําแหน่งบนโลกเพื่อแสดงผลข้อมูลระดับความสูง พารามิเตอร์นี้ใช้อาร์เรย์ของ LatLng

คุณอาจส่งพิกัดหลายรายการภายในอาร์เรย์จํานวนเท่าใดก็ได้ ตราบใดที่โควต้าเกินโควต้า โปรดทราบว่าเมื่อส่งพิกัดหลายรายการ ความถูกต้องของข้อมูลที่แสดงผลอาจมีความละเอียดต่ํากว่าเมื่อขอข้อมูลสําหรับพิกัดเดียว

ตัวอย่างคําขอเส้นทางตัวอย่าง

กฎออบเจ็กต์ PathElevationRequest มีช่องต่อไปนี้

{
  path[]: LatLng,
  samples: Number
}

ช่องเหล่านี้อธิบายไว้ด้านล่างนี้

• path (จําเป็น) กําหนดเส้นทางบนโลกเพื่อแสดงผลข้อมูลระดับความสูง พารามิเตอร์ path กําหนดชุดคู่ {ละติจูด,ลองจิจูด} ที่เรียงลําดับอย่างน้อย 2 คู่โดยใช้อาร์เรย์ของออบเจ็กต์ LatLng อย่างน้อย 2 รายการ
• samples (ต้องระบุ) ระบุจํานวนจุดตัวอย่างตลอดเส้นทางที่จะแสดงข้อมูลระดับความสูง พารามิเตอร์ samples จะหาร path ที่ระบุไปยังชุดจุดที่มีลําดับตามลําดับตลอดเส้นทาง

และเช่นเดียวกับคําขอตําแหน่ง พารามิเตอร์ path จะระบุชุดละติจูดและลองจิจูด แต่ path จะระบุชุดของจุดยอดมุมที่ต่างจากคําขอตามตําแหน่ง แทนที่จะแสดงผลข้อมูลระดับความสูงที่จุดยอด คําขอเส้นทางจะสุ่มตัวอย่างไปตามความยาวเส้นทาง ซึ่งตัวอย่างแต่ละรายการจะเท่าเทียมจากกันและกัน (รวมถึงปลายทาง)

การตอบสนองระดับความสูง

สําหรับคําขอที่ถูกต้องแต่ละคําขอ บริการ Elevate จะย้อนกลับไปยังการเรียกกลับที่ระบุชุดออบเจ็กต์ 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;
index.ts

หมายเหตุ: อ่านคู่มือเกี่ยวกับการใช้ TypeScript และ 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

หมายเหตุ: JavaScript จะรวบรวมจากข้อมูลโค้ด TypeScript

ดูตัวอย่าง

ลองใช้ตัวอย่าง

Stackblitz.com CodeSandbox.io JSFiddle.net GitPod.io Google Cloud Shell

ตัวอย่างต่อไปนี้สร้างโพลีไลน์ที่ระบุชุดพิกัดและแสดงข้อมูลระดับความสูงตามเส้นทางนั้นโดยใช้ GoogleVisual API (คุณต้องโหลด API นี้โดยใช้ตัวโหลดทั่วไปของ Google) คําขอระดับความสูงสร้างขึ้นโดยใช้ 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

หมายเหตุ: อ่านคู่มือเกี่ยวกับการใช้ TypeScript และ 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

หมายเหตุ: JavaScript จะรวบรวมจากข้อมูลโค้ด TypeScript

ดูตัวอย่าง

ลองใช้ตัวอย่าง

Stackblitz.com CodeSandbox.io JSFiddle.net GitPod.io Google Cloud Shell