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:
- Google Cloud Console'a gidin.
- Proje seç düğmesini tıklayın, ardından Maps JavaScript API için oluşturduğunuz projeyi seçin ve Aç'ı tıklayın.
- Kontrol panelindeki API listesinde Elevation API'yi bulun.
- API'yi listede görürseniz hazırsınız demektir. API listede yoksa etkinleştirin:
- 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.
- Elevation API'yi arayın ve ardından 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'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, birPathElevationRequest
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 fazlaLatLng
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, verilenpath
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österirREQUEST_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 isteklerindelocation
öğ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 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;