บริการระดับความสูง

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

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

ภาพรวม

ดูข้อมูลอ้างอิง Maps JavaScript API เพิ่มเติมที่หัวข้อต่อไปนี้ ระดับความสูง

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

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

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

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

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

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

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

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

ราคา

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

นโยบาย

การใช้บริการระดับความสูงต้องเป็นไปตามนโยบายที่อธิบายไว้สำหรับ Elevation API

คำขอยกระดับ

การเข้าถึงบริการระดับความสูงเป็นแบบไม่พร้อมกัน เนื่องจาก Google Maps API จำเป็นต้องเรียกใช้เซิร์ฟเวอร์ภายนอก คุณจึงต้องส่งเมธอด callback เพื่อดำเนินการเมื่อคําขอเสร็จสมบูรณ์ เมธอด 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 กำหนดชุดคู่ {latitude,longitude} ที่เรียงลำดับแล้วอย่างน้อย 2 คู่โดยใช้อาร์เรย์ของออบเจ็กต์ LatLng อย่างน้อย 2 รายการ
• samples (ต้องระบุ) ระบุจํานวนจุดตัวอย่างตามเส้นทางที่จะแสดงผลข้อมูลระดับความสูง พารามิเตอร์ samples จะแบ่ง path ที่กำหนดออกเป็นชุดจุดที่เรียงตามลำดับซึ่งอยู่ห่างเท่าๆ กันตลอดเส้นทาง

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

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

สําหรับคําขอที่ถูกต้องแต่ละรายการ บริการ Elevation จะแสดงชุดออบเจ็กต์ ElevationResult ควบคู่ไปกับออบเจ็กต์ ElevationStatus ไปยังการเรียกกลับที่กําหนด

สถานะการยกระดับ

คําขอการเลื่อนระดับแต่ละรายการจะแสดงผลรหัส ElevationStatus ภายในฟังก์ชัน Callback รหัส status นี้จะมีค่าใดค่าหนึ่งต่อไปนี้

• OK ระบุว่าคำขอบริการสำเร็จ
• INVALID_REQUEST บ่งบอกว่าคำขอบริการมีรูปแบบไม่ถูกต้อง
• OVER_QUERY_LIMIT ระบุว่าผู้ขอใช้โควต้าเกิน
• REQUEST_DENIED บ่งบอกว่าบริการดำเนินการตามคำขอไม่สำเร็จ ซึ่งอาจเป็นเพราะพารามิเตอร์ไม่ถูกต้อง
• UNKNOWN_ERROR บ่งบอกถึงข้อผิดพลาดที่ไม่รู้จัก

คุณควรตรวจสอบว่าการติดต่อกลับสําเร็จหรือไม่โดยดูรหัสสถานะนี้สําหรับ OK

ผลการยกระดับ

เมื่อดำเนินการสำเร็จ อาร์กิวเมนต์ results ของฟังก์ชัน Callback จะมีชุดออบเจ็กต์ 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 }, // 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

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

ดูตัวอย่าง

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

JSFiddle.net Google Cloud Shell

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

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

ดูตัวอย่าง

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

JSFiddle.net Google Cloud Shell