Yükseklik Hizmeti

Genel Bakış

Elevation Service, okyanus tabanındaki derinlik konumları (negatif değerler döndürür) dahil olmak üzere dünya yüzeyindeki konumlar için yükseklik verileri sağlar. Google'ın, istediğiniz tam konumda kesin yükseklik ölçümlerine sahip olmadığı durumlarda hizmet, en yakın dört konumu kullanarak ortalama bir değer hesaplar ve döndürür.

ElevationService nesnesi, dünya üzerindeki konumları yükseklik verileri için sorgulamanıza olanak tanıyan basit bir arayüz sunar. Ayrıca, yollar boyunca örneklenmiş yükseklik verileri isteyerek rotalar boyunca eşit mesafeli yükseklik değişikliklerini hesaplayabilirsiniz. ElevationService nesnesi, yükseklik isteklerini alan ve yükseklik verilerini döndüren Google Maps API Elevation Service ile iletişim kurar.

Elevation Service ile yürüyüş ve bisiklet uygulamaları, mobil konumlandırma uygulamaları veya düşük çözünürlüklü ölçüm uygulamaları geliştirebilirsiniz.

Başlarken

Maps JavaScript API'deki Elevation hizmetini kullanmadan önce, Google Cloud Console'da Elevation API'nin Maps JavaScript API için ayarladığınız projede etkinleştirildiğinden emin olun.

Etkin API'lerinizin listesini görüntülemek için:

  1. Google Cloud Console'a gidin.
  2. Proje seçin düğmesini tıklayın, ardından Maps JavaScript API için oluşturduğunuz projeyi seçip Aç'ı tıklayın.
  3. Kontrol panelindeki API listesinde Elevation API'yi bulun.
  4. API'yi listede görüyorsanız hazırsınız demektir. API listede yoksa etkinleştirin:
    1. Kitaplık sekmesini görüntülemek için sayfanın üst kısmında API'Yİ ETKİNLEŞTİR'i seçin. Alternatif olarak, soldaki menüden Kitaplık'ı seçin.
    2. Elevation API'yi arayın ve sonuç listesinden seçin.
    3. ETKİNLEŞTİR'i seçin. İşlem tamamlandığında Elevation API, Kontrol Paneli'ndeki API'ler listesinde görünür.

Fiyatlandırma ve politikalar

Fiyatlandırma

JavaScript Elevation hizmetinin fiyatlandırma ve kullanım politikaları hakkında bilgi edinmek için Elevation API ile ilgili Kullanım ve Faturalandırma bölümüne bakın.

Politikalar

Elevation hizmetinin kullanımı, Elevation API için açıklanan politikalara uygun olmalıdır.

Yükseltme İstekleri

Google Haritalar API'sinin harici bir sunucuya çağrı yapması gerektiğinden, Elevation hizmetine erişim eşzamansızdır. Bu nedenle, isteğin tamamlanmasının ardından yürütülecek bir geri çağırma yöntemi iletmeniz gerekir. Bu geri çağırma yöntemi, sonuçları işlemelidir. Elevation hizmetinin bir durum kodu (ElevationStatus) ve ayrı ElevationResult nesnelerinden oluşan bir dizi döndürdüğünü unutmayın.

ElevationService iki tür isteği işler:

  • getElevationForLocations() yöntemini kullanarak ayrı, farklı konumlar için istekler. Bu yönteme, LocationElevationRequest nesnesi kullanılarak bir veya daha fazla konumun listesi iletilir.
  • PathElevationRequest nesnesi içinde sıralı bir yol köşeleri kümesi iletilen getElevationAlongPath() yöntemini kullanarak bir yol boyunca bir dizi bağlı noktanın rakımını öğrenme istekleri. Yollar boyunca rakım bilgisi isterken, o yol boyunca kaç örnek almak istediğinizi belirten bir parametre de iletmeniz gerekir.

Bu yöntemlerin her biri, döndürülen ElevationResult ve ElevationStatus nesnelerini işlemek için bir geri çağırma yöntemi de iletmelidir.

Konum Yükseltme İstekleri

LocationElevationRequest nesne değişmez değeri aşağıdaki alanı içerir:

{
  locations[]: LatLng
}

locations (gerekli), rakım verilerinin döndürüleceği dünya üzerindeki konumları tanımlar. Bu parametre, bir LatLng dizisi alır.

Hizmet kotalarını aşmadığınız sürece bir dizi içinde istediğiniz sayıda koordinat iletebilirsiniz. Birden fazla koordinat iletirken, döndürülen verilerin doğruluğunun tek bir koordinat için veri isterken olduğundan daha düşük çözünürlükte olabileceğini unutmayın.

Örneklenen Yol Rakımı İstekleri

PathElevationRequest nesne değişmez değeri aşağıdaki alanları içerir:

{
  path[]: LatLng,
  samples: Number
}

Bu alanlar aşağıda açıklanmıştır:

  • path (gerekli), yükseklik verilerinin döndürüleceği dünya üzerindeki bir yolu tanımlar. path parametresi, iki veya daha fazla LatLng nesnesinden oluşan bir dizi kullanarak iki veya daha fazla sıralı {enlem,boylam} çiftinden oluşan bir küme tanımlar.
  • samples (gerekli), yükseklik verilerinin döndürüleceği yol boyunca örnek noktaların sayısını belirtir. samples parametresi, verilen path değerini yol boyunca eşit uzaklıktaki sıralı bir nokta kümesine böler.

Konuma dayalı isteklerde olduğu gibi path parametresi, bir dizi enlem ve boylam değerini belirtir. Ancak konumsal bir isteğin aksine path, sıralı bir köşe kümesi belirtir. Yol istekleri, tepe noktalarındaki yükseklik verilerini döndürmek yerine yolun uzunluğu boyunca örneklenir. Her örnek, birbirinden eşit uzaklıktadır (uç noktalar dahil).

Rakım Yanıtları

Her geçerli istek için Elevation hizmeti, tanımlanan geri çağırmaya bir ElevationStatus nesnesiyle birlikte bir dizi ElevationResult nesnesi döndürür.

Yükseltme Durumları

Her yükseltme isteği, geri çağırma işlevinde bir ElevationStatus kodu döndürür. Bu status kodu, aşağıdaki değerlerden birini içerir:

  • OK hizmet isteğinin başarılı olduğunu gösterir
  • INVALID_REQUEST, hizmet isteğinin yanlış biçimlendirildiğini gösterir.
  • OVER_QUERY_LIMIT, talep eden kullanıcının kotayı aştığını gösterir.
  • REQUEST_DENIED, hizmetin isteği tamamlamadığını gösterir. Bunun nedeni muhtemelen geçersiz bir parametredir.
  • Bilinmeyen bir hatayı gösteren UNKNOWN_ERROR

OK için bu durum kodunu inceleyerek geri çağırma işleminizin başarılı olup olmadığını kontrol etmeniz gerekir.

Rakım Sonuçları

İşlem başarılı olursa geri çağırma işlevinizin results bağımsız değişkeni bir dizi ElevationResult nesnesi içerir. Bu nesneler aşağıdaki öğeleri içerir:

  • Yükseklik verilerinin hesaplandığı konumun location öğesi (LatLng nesneleri içerir). Yol istekleri için location öğeleri kümesinin, yol boyunca örneklenen noktaları içereceğini unutmayın.
  • Konumun metre cinsinden yüksekliğini gösteren bir elevation öğesi.
  • Yüksekliğin enterpolasyonunun yapıldığı veri noktaları arasındaki maksimum mesafeyi metre cinsinden gösteren bir resolution değeri. Çözünürlük bilinmiyorsa bu özellik eksik olur. Birden fazla nokta iletildiğinde rakım verilerinin daha kaba (daha büyük resolution değerleri) hale geldiğini unutmayın. Bir noktanın en doğru yükseklik değerini elde etmek için noktanın bağımsız olarak sorgulanması gerekir.

Yükseklik Örnekleri

Aşağıdaki kod, LocationElevationRequest nesnesini kullanarak haritadaki bir tıklamayı rakım isteğine dönüştürür:

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();
Örneği görüntüleyin

Aşağıdaki örnekte, bir koordinat kümesi verildiğinde çoklu çizgi oluşturulmakta ve Google Görselleştirme API'si kullanılarak bu yol boyunca yükseklik verileri gösterilmektedir. (Bu API'yi Google Common Loader'ı kullanarak yüklemeniz gerekir.) Rakım isteği, PathElevationRequest kullanılarak oluşturulur:

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;
Örneği görüntüleyin