Tırmanma Hizmeti

Genel bakış

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

ElevationService nesnesi, yükseklik verileri için dünyadaki konumları sorgulamak üzere basit bir arayüz sunar. Ayrıca, yollar boyunca örneklenmiş yükseklik verileri isteyebilirsiniz. Bu sayede rotalar boyunca eşit uzaklık değişikliklerini hesaplayabilirsiniz. ElevationService nesnesi, yükseklik isteklerini alan ve yükseklik verilerini döndüren Google Haritalar API Yükseklik Hizmeti ile iletişim kurar.

Rakım hizmetiyle yürüyüş ve bisiklet uygulamaları, mobil konumlandırma uygulamaları veya düşük çözünürlüklü harita oluşturma uygulamaları geliştirebilirsiniz.

Kullanmaya başlama

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

Etkin API'ler listenizi 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çin ve 'ı tıklayın.
  3. Kontrol Paneli'ndeki API listesinde Elevation API'yi bulun.
  4. Listede API'yi görüyorsanız her şey hazır demektir. API listede yoksa etkinleştirin:
    1. Sayfanın üst kısmında Kitaplık sekmesini görüntülemek için API'yi ETKİNLEŞTİR'i seçin. Alternatif olarak, sol taraftaki menüden Kitaplık'ı seçin.
    2. Elevation API'yi arayın ve 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 tarihinden itibaren Haritalar, Rotalar ve Yerler için yeni bir kullandıkça öde fiyatlandırma planı yürürlüğe girdi. JavaScript Elevation hizmeti kullanımınızla ilgili yeni fiyatlandırma ve kullanım sınırları hakkında daha fazla bilgi edinmek için Elevation API Kullanım ve Faturalandırma bölümünü inceleyin.

Politikalar

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

Yükselti İstekleri

Google Maps API'nin harici bir sunucuya çağrı yapması gerektiğinden, Elevation hizmetine erişim eşzamansız olarak gerçekleştirilmektedir. Bu nedenle, isteğin tamamlanmasının ardından yürütülecek bir callback yöntemi iletmeniz gerekir. Bu geri çağırma yöntemi sonuçları işlemelidir. Rakım hizmetinin, bir durum kodu (ElevationStatus) ve ayrı ElevationResult nesneleri dizisi döndürdüğünü unutmayın.

ElevationService iki istek türünü ele alır:

  • getElevationForLocations() yöntemiyle ayrı, ayrı konum istekleri. Bu yöntem, bir LocationElevationRequest nesnesi kullanarak bir veya daha fazla konumun listesini iletir.
  • getElevationAlongPath() yöntemini kullanarak bir yol boyunca bir dizi bağlı nokta üzerinde irtifa istekleri. Bu yöntem, PathElevationRequest nesnesi içinde sıralı bir yol köşeleri grubu iletir. Yollarda 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 callback yöntemi de iletmelidir.

Konum Rakımı İstekleri

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

{
  locations[]: LatLng
}

locations (zorunlu), dünya üzerinde yükseklik verilerinin döndürüleceği konumları tanımlar. Bu parametre LatLng saniyelik bir dizi alır.

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

Örneklenmiş Yol Yükselti İ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 (zorunlu), dünya üzerinde yükseklik verilerinin döndürüleceği bir yolu tanımlar. path parametresi, iki veya daha fazla LatLng nesnesinden oluşan bir dizi kullanarak iki veya daha fazla sıralı {latitude,longitude} çiftinden oluşan bir kümeyi tanımlar.
  • samples (zorunlu), bir yol boyunca yükseklik verilerinin döndürüleceği örnek noktalarının sayısını belirtir. samples parametresi, verilen path değerini yol boyunca eşit uzaklıkta sıralı bir dizi noktaya böler.

Konumlandırma isteklerinde olduğu gibi path parametresi de bir dizi enlem ve boylam değeri belirtir. Bununla birlikte, konumlama isteğinden farklı olarak path, sıralı bir köşe noktası grubu belirtir. Köşelerde yükseklik verileri döndürmek yerine, yol istekleri yol boyunca örneklenir. Burada her örnek, uç noktalar da dahil olmak üzere birbirinden eşit uzaklıktadır.

Yükselti Yanıtları

Yükseklik hizmeti, geçerli olan her istek için ElevationStatus nesnesiyle birlikte tanımlanmış ElevationResult nesne grubunu geri çağırmaya döndürür.

Yükselti Durumları

Her yükseltme 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:

  • Hizmet isteğinin başarılı olduğunu belirten OK
  • Hizmet isteğinin hatalı olduğunu belirten INVALID_REQUEST
  • İstekte bulunanın kotayı aştığını gösteren OVER_QUERY_LIMIT
  • Hizmetin isteği tamamlamadığını belirten REQUEST_DENIED. Bunun nedeni geçersiz bir parametre olabilir
  • Bilinmeyen bir hata olduğunu gösteren UNKNOWN_ERROR

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

Yükselti Sonuçları

Başarılı olduğunda, geri çağırma işlevinizin results bağımsız değişkeni bir ElevationResult nesne kümesi içerir. Bu nesneler aşağıdaki öğeleri içerir:

  • Yükseklik verilerinin hesaplandığı konumun bir location öğesi (LatLng nesne içeren). Yol istekleri için location öğe grubunun, yol boyunca örneklenmiş noktaları içereceğini unutmayın.
  • Konumun metre cinsinden yüksekliğini gösteren elevation öğesi.
  • Yüksekliğin interpolasyonu yapılan veri noktaları arasındaki maksimum mesafeyi metre cinsinden gösteren resolution değeri. Çözünürlük bilinmiyorsa bu özellik eksik olacaktır. Birden çok nokta geçirildiğinde yükseklik verilerinin daha yüzeysel hale geleceğini (daha büyük resolution değerleri) unutmayın. Bir nokta için en doğru yükseklik değerini elde etmek üzere bu nokta bağımsız olarak sorgulanmalıdır.

Yükseklik Örnekleri

Aşağıdaki kod, LocationElevationRequest nesnesini kullanarak harita üzerindeki bir tıklamayı yükseklik isteğine çevirir:

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 },
    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 verilen bir çoklu çizgi oluşturulur 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.) PathElevationRequest kullanılarak bir yükseltme isteği 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 },
    { lat: 36.606, lng: -118.0638 },
    { lat: 36.433, lng: -117.951 },
    { lat: 36.588, lng: -116.943 },
    { lat: 36.34, lng: -117.468 },
    { 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