Yükseklik Hizmeti

Genel Bakış

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

ElevationService nesnesi, dünya üzerindeki konumları rakım verileri için sorgulayabileceğiniz basit bir arayüz sağlar. Ayrıca, rotalar boyunca eşit aralıklı yükseklik değişikliklerini hesaplamanıza olanak tanıyan, yollardaki örneklenmiş yükseklik verilerini isteyebilirsiniz. ElevationService nesnesi, rakım isteklerini alan ve rakım verilerini döndüren Google Haritalar API 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ü anket uygulamaları geliştirebilirsiniz.

Başlarken

Maps JavaScript API'de Rakım hizmetini kullanmadan önce, Elevation API'nin Google Cloud Console'da, Maps JavaScript API için oluşturduğunuz 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ç düğmesini tıklayın, ardından Maps JavaScript API için oluşturduğunuz projeyi seçin ve 'ı tıklayın.
  3. Kontrol panelindeki API listesinde Elevation API'yi bulun.
  4. API'yi listede görürseniz hazırsınız demektir. API listede yoksa etkinleştirin:
    1. Sayfanın üst kısmında API'yi etkinleştir'i seçerek Kitaplık sekmesini görüntüleyin. Alternatif olarak, sol taraftaki menüden Kitaplık'ı da seçebilirsiniz.
    2. Elevation API'yi arayın ve ardından sonuçlar listesinden seçin.
    3. ETKİNLEŞTİR'i seçin. İşlem tamamlandığında Kontrol paneli'ndeki API listesinde Elevation API görünür.

Fiyatlandırma ve politikalar

Fiyatlandırma

16 Temmuz 2018'den itibaren Haritalar, Rotalar ve Yerler için kullandıkça öde türünde yeni bir fiyatlandırma planı kullanıma sunuldu. JavaScript Rakım hizmetini kullanımınızla ilgili yeni fiyatlandırma ve kullanım sınırlamaları hakkında daha fazla bilgi edinmek için Elevation API'nin Kullanım ve Faturalandırma bölümüne bakın.

Politikalar

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

Rakım İstekleri

Google Haritalar API'sinin harici bir sunucuya çağrı yapması gerektiğinden, Rakım hizmetine erişme işlemi eşzamanlı değildir. Bu nedenle, istek tamamlandıktan sonra çalıştırılacak 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ı bir ElevationResult nesnesi dizisi döndürdüğünü unutmayın.

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

  • getElevationForLocations() yöntemini kullanarak ayrı, ayrı konumlar için isteklerde bulunulur. Bu yönteme, LocationElevationRequest nesnesi kullanılarak bir veya daha fazla konumun listesi iletilir.
  • getElevationAlongPath() yöntemi kullanılarak bir yol boyunca birbirine bağlı bir dizi noktadaki yükseklik istekleri. Bu yöntem, bir PathElevationRequest nesnesi içinde sıralı bir yol köşesi grubu ile iletilir. Yollar boyunca yükseklik isteğinde bulunurken, söz konusu 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üksekliği İstekleri

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

{
  locations[]: LatLng
}

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

Hizmet kotalarını aşmamak koşuluyla, bir dizi içinde dilediğiniz sayıda koordinat iletebilirsiniz. Birden fazla koordinat iletirken döndürülen verilerin doğruluğunun, tek bir koordinat için veri isteğinde bulunulduğundan daha düşük çözünürlükte olabileceğini unutmayın.

Örneklenmiş Yol Yükseltisi İstekleri

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

{
  path[]: LatLng,
  samples: Number
}

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

  • path (zorunlu), yeryüzünde yükseklik verilerinin döndürüleceği bir yol tanımlar. path parametresi, iki veya daha fazla LatLng nesnesi dizisi kullanarak iki veya daha fazla sıralı {latitude,longitude} çifti 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 mesafeli noktalardan oluşan sıralı bir kümeye böler.

Konum istekleri gibi path parametresi de bir dizi enlem ve boylam değerini belirtir. Ancak path, konumsal isteklerin aksine sıralı bir köşe noktası kümesi belirtir. Yol isteklerinde, köşe noktalarında yükseklik verileri döndürülmek yerine yolun uzunluğu boyunca örnekleme yapılır. Bu örneklemede her örnek, uç noktalar dahil olmak üzere birbirinden eşit uzaklıktadır.

Yükseklik Yanıtları

Elevation hizmeti, her geçerli istek için tanımlanan geri çağırma işlevine bir ElevationStatus nesnesi ile birlikte bir dizi ElevationResult nesnesi döndürür.

Rakım Durumları

Her yükseklik 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ği başarıyla tamamlandığını gösterir.
  • INVALID_REQUEST, hizmet isteğinin yanlış biçimlendirildiğini gösterir.
  • OVER_QUERY_LIMIT, istek sahibinin kotayı aştığını gösterir
  • REQUEST_DENIED, hizmetin isteği tamamlamadığını gösterir. Bu durum, muhtemelen geçersiz bir parametre nedeniyle yaşanmıştır.
  • Bilinmeyen bir hatayı belirten UNKNOWN_ERROR

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

Rakım Sonuçları

İşlev 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 nesneleri içerir). Yol isteklerinde location öğelerinin, yol boyunca örneklenen noktaları içereceğini unutmayın.
  • Konumun metre cinsinden yüksekliğini belirten bir elevation öğesi.
  • Yüksekliğin interpolasyon uygulandığı veri noktaları arasındaki maksimum mesafeyi metre cinsinden belirten bir resolution değeri. Çözünürlük bilinmiyorsa bu özellik eksik olur. Birden fazla nokta geçtiğinde yükseklik verilerinin daha kaba (resolution değerleri daha büyük) hale geldiğini unutmayın. Bir noktanın en doğru yükseklik değerini elde etmek için bu nokta bağımsız olarak sorgulanır.

Yükseklik Örnekleri

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

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;

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

Örneği Deneyin

Aşağıdaki örnekte, bir dizi koordinat verildiğinde bir ç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.) Bir yükseklik 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

Örneği Deneyin