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:
- Google Cloud Console'a gidin.
- Proje seçin düğmesini tıklayın, ardından Maps JavaScript API için oluşturduğunuz projeyi seçin ve Aç'ı tıklayın.
- Kontrol Paneli'ndeki API listesinde Elevation API'yi bulun.
- Listede API'yi görüyorsanız her şey hazır demektir. API listede yoksa etkinleştirin:
- 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.
- Elevation API'yi arayın ve sonuçlar listesinden seçin.
- 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, birLocationElevationRequest
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 fazlaLatLng
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, verilenpath
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çinlocation
öğ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ükresolution
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 }, // 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 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 }, // 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;