Yükseklik Hizmeti

Genel Bakış

Yükseklik hizmeti, okyanus tabanındaki derinlik konumları (negatif değerler döndürür) da dahil olmak üzere dünya yüzeyindeki konumlar için yükseklik verileri sağlar. Google'ın istediğiniz konumda tam 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, yeryüzündeki konumları rakım verileri için sorgulamanıza olanak tanıyan basit bir arayüz sağlar. Ayrıca, yollar boyunca örneklenmiş yükseklik verileri isteyebilir, böylece rotalar boyunca eşit mesafedeki yükseklik değişikliklerini hesaplayabilirsiniz. ElevationService nesnesi, rakım isteklerini alan ve rakım verilerini döndüren Google Haritalar API'si Rakım Hizmeti ile iletişim kurar.

Yükseklik hizmetiyle yürüyüş ve bisiklet uygulamaları, mobil konumlandırma uygulamaları veya düşük çözünürlüklü ölçme 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.

Etkinleştirilen API'lerinizin listesini görüntülemek için:

  1. Google Cloud Console'a gidin.
  2. Proje seç düğmesini tıklayın, ardından Maps JavaScript API için ayarladığınız projeyi seçip Aç'ı tıklayın.
  3. Kontrol panelindeki API listesinde Elevation API'yi bulun.
  4. Listede API'yi görüyorsanız hazırsınız demektir. API listelenmemişse 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, sol taraftaki yan 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 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'nin Kullanım ve Faturalandırma bölümüne bakın.

Politikalar

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

Yükseltme İstekleri

Google Haritalar API'sinin harici bir sunucuya çağrı yapması gerektiğinden, Rakım hizmetine erişim eşzamansızdır. Bu nedenle, istek tamamlandığında yürütülecek bir geri çağırma yöntemi iletmeniz gerekir. Bu geri çağırma yöntemi, sonuçları işlemelidir. Yükseltme hizmetinin bir durum kodu (ElevationStatus) ve ayrı ElevationResult nesnelerden oluşan bir dizi döndürdüğünü unutmayın.

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

  • getElevationForLocations() yöntemi kullanılarak ayrı ve bağımsız konumlar için yapılan istekler. Bu yöntemde, LocationElevationRequest nesnesi kullanılarak bir veya daha fazla konumun listesi iletilir.
  • getElevationAlongPath() yöntemi kullanılarak bir yol boyunca birbirine bağlı bir dizi noktada yükseklik isteğinde bulunulur. Bu yöntemde, PathElevationRequest nesnesi içinde sıralı bir yol köşe noktaları kümesi iletilir. Yollar boyunca yükseklik isteğinde bulunurken bu 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öntemini de geçirmelidir.

Konum Yüksekliği İstekleri

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

{
  locations[]: LatLng
}

locations (zorunlu), rakım verilerinin döndürüleceği yeryüzündeki konumları tanımlar. Bu parametre, LatLng dizisini alır.

Hizmet kotalarını aşmadığınız sürece bir dizide istediğiniz sayıda koordinat iletebilirsiniz. Birden fazla koordinat iletilirken döndürülen verilerin doğruluğunun, tek bir koordinat için veri isteğinde bulunulurken elde edilen verilerin doğruluğundan daha düşük çözünürlüklü olabileceğini unutmayın.

Örneklenen Yol Yüksekliği İstekleri

Bir 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 (zorunlu), yükseklik verilerinin döndürüleceği, dünyadaki bir yolu tanımlar. path parametresi, iki veya daha fazla LatLng nesnesinin dizisini kullanarak iki veya daha fazla sıralı {enlem,boylam} çiftini tanımlar.
  • samples (zorunlu), bir yol boyunca yükseklik verilerinin döndürüleceği örnek nokta sayısını belirtir. samples parametresi, verilen path değerini yol boyunca eşit mesafede bulunan sıralı bir nokta kümesine böler.

Konum isteklerinde olduğu gibi, path parametresi bir dizi enlem ve boylam değeri belirtir. Ancak konumsal bir isteğin aksine, path sıralı bir köşe kümesi belirtir. Yükseklik verilerini köşelerde döndürmek yerine, yol istekleri yolun uzunluğu boyunca örneklenir. Her örnek, uç noktalar dahil olmak üzere birbirinden eşit uzaklıktadır.

Yükseklik Yanıtları

Yükseklik hizmeti, her geçerli istek için tanımlanan geri çağırmaya bir ElevationResult nesne grubu ve bir ElevationStatus nesnesi döndürür.

Yükseklik durumları

Her yükseklik isteği, geri çağırma işlevi içinde 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, isteği gönderenin 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 arama işleminizin başarılı olup olmadığını kontrol etmeniz gerekir.

Yükseklik Sonuçları

İşlem başarılı olduğunda, 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 nesnelerini içerir). Yol isteklerinde 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ükseklik değerinin enterpolasyonla hesaplandığı veri noktaları arasındaki maksimum mesafeyi metre cinsinden gösteren resolution değeri. Çözünürlük bilinmiyorsa bu özellik eksik olur. Birden fazla nokta iletildiğinde yükseklik verilerinin daha kaba (daha büyük resolution değerler) hale geldiğini unutmayın. Bir nokta için en doğru yükseklik değerini elde etmek üzere bağımsız olarak sorgulanmalıdır.

Yükseklik örnekleri

Aşağıdaki kod, bir haritadaki tıklamayı LocationElevationRequest nesnesini kullanarak yükseklik 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 dizi koordinat verilerek çoklu çizgi oluşturulur ve Google Visualization API kullanılarak bu yol boyunca yükseklik verileri gösterilir. (Bu API'yi Google Common Loader'ı kullanarak yüklemeniz gerekir.) Yükseltme 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