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

ภาพรวม

บริการระดับความสูงจะให้ข้อมูลระดับความสูงของสถานที่ต่างๆ บนพื้นผิวโลก รวมถึงสถานที่ที่มีความลึกบนพื้น มหาสมุทร (ซึ่งแสดงผลเป็นค่าติดลบ) ในกรณีที่ 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. ค้นหา Elevation API จากรายการ API ในแดชบอร์ด
  4. หากเห็น API ในรายการ แสดงว่าคุณพร้อมใช้งานแล้ว หากไม่เห็น API ในรายการ ให้เปิดใช้โดยทำดังนี้
    1. เลือกเปิดใช้ API ที่ด้านบนของหน้าเพื่อแสดงแท็บ คลัง หรือเลือกคลัง จากเมนูด้านซ้าย
    2. ค้นหา Elevation API แล้วเลือกจากรายการผลการค้นหา
    3. เลือกเปิดใช้ เมื่อกระบวนการเสร็จสิ้น Elevation API จะปรากฏในรายการ API ใน แดชบอร์ด

การกำหนดราคาและนโยบาย

ราคา

ดูข้อมูลเกี่ยวกับการกำหนดราคาและนโยบายการใช้งานสำหรับบริการระดับความสูงของ 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 กำหนดชุดคู่ {ละติจูด,ลองจิจูด} อย่างน้อย 2 คู่ที่เรียงลำดับแล้วโดยใช้อาร์เรย์ของออบเจ็กต์ LatLng อย่างน้อย 2 รายการ
  • samples (ต้องระบุ) ระบุจำนวนจุดตัวอย่างตามเส้นทางที่จะแสดงผลข้อมูลระดับความสูง พารามิเตอร์ samples จะแบ่ง path ที่ระบุออกเป็นชุดจุดที่อยู่ห่างเท่าๆ กันตามเส้นทางที่เรียงลำดับแล้ว

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

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

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

สถานะระดับความสูง

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

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

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

ผลลัพธ์ระดับความสูง

เมื่อสำเร็จ อาร์กิวเมนต์ results ของฟังก์ชัน Callback จะมีชุดออบเจ็กต์ ElevationResult ออบเจ็กต์เหล่านี้มีองค์ประกอบต่อไปนี้

  • องค์ประกอบ location (ที่มีออบเจ็กต์ LatLng ) ของตำแหน่งที่จะคำนวณข้อมูลระดับความสูง โปรดทราบ ว่าสำหรับคำขอเส้นทาง ชุดองค์ประกอบ location จะมี จุดที่สุ่มตัวอย่างตามเส้นทาง
  • องค์ประกอบ elevation ที่ระบุระดับความสูงของ สถานที่เป็นเมตร
  • ค่า resolution ที่ระบุระยะทางสูงสุดระหว่าง จุดข้อมูลที่ใช้ประมาณค่าระดับความสูงเป็นเมตร พร็อพเพอร์ตี้นี้ จะหายไปหากไม่ทราบความละเอียด โปรดทราบว่า ข้อมูลระดับความสูงจะหยาบขึ้น (ค่า resolution มากขึ้น) เมื่อส่งจุดหลายจุด หากต้องการรับค่าระดับความสูงที่แม่นยำที่สุดสำหรับจุดหนึ่งๆ คุณควรค้นหาจุดนั้นแยกกัน

ตัวอย่างระดับความสูง

โค้ดต่อไปนี้จะแปลการคลิกบนแผนที่เป็นคำขอระดับความสูง โดยใช้ออบเจ็กต์ 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();

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();
ดูตัวอย่าง

ตัวอย่างต่อไปนี้สร้างเส้นประกอบจากชุดพิกัด และแสดงข้อมูลระดับความสูงตามเส้นทางนั้นโดยใช้ 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;

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;
ดูตัวอย่าง