Przegląd
Usługa wysokości względnej udostępnia dane o wysokości dotyczące lokalizacji na powierzchni ziemi, w tym głębokość lokalizacji na dnie oceanu (które zwracają wartości ujemne). W przypadkach, gdy Google nie ma dokładnych pomiarów wysokości w dokładnie wybranej lokalizacji, usługa interpoluje i zwraca średnią wartość za pomocą czterech najbliższych lokalizacji.
Obiekt ElevationService
udostępnia prosty interfejs do wysyłania zapytań o lokalizacje na Ziemi w celu uzyskania danych o wzniesieniu. Możesz też poprosić o próbkowanie danych dotyczących wysokości wzdłuż ścieżek, aby obliczyć odpowiednie zmiany wysokości na trasach. Obiekt ElevationService
komunikuje się z usługą Elevation API w Mapach Google, która odbiera żądania o wzniesieniu i zwraca dane o wysokości.
Usługa elewacji umożliwia tworzenie aplikacji dla wycieczek pieszych i rowerowych, aplikacji do pozycjonowania mobilnego oraz aplikacji do geodezji.
Pierwsze kroki
Zanim użyjesz usługi Elevation API w Maps JavaScript API, najpierw upewnij się, że interfejs Elevation API jest włączony w Google Cloud Console w tym samym projekcie, który masz skonfigurowany w Maps JavaScript API.
Aby wyświetlić listę włączonych interfejsów API:
- Otwórz Google Cloud Console.
- Kliknij przycisk Wybierz projekt, a następnie wybierz ten sam projekt, który został skonfigurowany dla interfejsu Maps JavaScript API, i kliknij Otwórz.
- Na liście interfejsów API w panelu znajdź Elevation API.
- Jeśli interfejs API jest widoczny na liście, nie musisz nic robić. Jeśli interfejsu API nie ma na liście, włącz go:
- U góry strony wybierz WŁĄCZ API, aby wyświetlić kartę Biblioteka. W menu po lewej stronie możesz też wybrać Biblioteka.
- Wyszukaj interfejs Elevation API i wybierz go z listy wyników.
- Kliknij WŁĄCZ. Gdy proces dobiegnie końca, interfejs Elevation API pojawi się na liście interfejsów API w panelu.
Ceny i zasady
Ceny
16 lipca 2018 roku w Mapach, trasach i miejscach jest dostępny nowy cennik płatności według wykorzystania. Więcej informacji o nowych limitach cen i wykorzystania podczas korzystania z usługi Elevation API znajdziesz w artykule Usage and Billing (Użycie i płatności) do wykorzystania w interfejsie Elevation API.
Zasady
Korzystanie z usługi Elevation musi być zgodne z zasadami opisanymi w interfejsie Elevation API.
Prośby o wzniesienie
Dostęp do usługi Elevation jest asynchroniczny, bo API Map Google musi wywoływać serwer zewnętrzny. Z tego powodu musisz przekazać metodę wywołania zwrotnego, aby wykonać żądanie. Ta metoda wywołania zwrotnego powinna przetworzyć wyniki. Zwróć uwagę, że usługa Elevator zwraca kod stanu (ElevationStatus
) oraz tablicę oddzielnych obiektów ElevationResult
.
ElevationService
obsługuje 2 typy żądań:
- Żądania osobnych lokalizacji konkretnych przy użyciu metody
getElevationForLocations()
, która jest przekazywana do listy co najmniej 1 lokalizacji za pomocą obiektuLocationElevationRequest
. - Żądania dotyczące wysokości w szeregu połączonych punktów na ścieżce przy użyciu metody
getElevationAlongPath()
, która jest przekazywana do zestawu wierzchołków ścieżki w obiekciePathElevationRequest
. Wysyłając prośbę o wzniesienie wzdłuż ścieżek, musisz też przekazać parametr wskazujący liczbę prób, które chcesz obrać w tej ścieżce.
Każda z tych metod musi też przekazywać metodę wywołania zwrotnego, by obsługiwała zwrócone obiekty ElevationResult
i ElevationStatus
.
Prośby o podniesienie lokalizacji
Literał obiektu LocationElevationRequest
zawiera to pole:
{ locations[]: LatLng }
Atrybut locations
(wymagany) określa lokalizacje na Ziemi, z których mają być zwracane dane o wysokości. Ten parametr przyjmuje tablicę LatLng
s.
W tablicy możesz ustawić dowolną liczbę wielu współrzędnych, pod warunkiem że nie przekroczysz limitów usługi. Pamiętaj, że w przypadku przesyłania wielu współrzędnych dokładność zwracanych danych może być niższa niż w przypadku żądania pojedynczej współrzędnej.
Próbki wzniesienia ścieżki
Literał obiektu PathElevationRequest
zawiera te pola:
{ path[]: LatLng, samples: Number }
Te pola objaśniamy poniżej.
- Atrybut
path
(wymagany) definiuje ścieżkę na Ziemi, dla której należy zwracać dane o wysokości. Parametrpath
określa zestaw 2 lub większej liczby par {szerokość_długości geograficznej}, używając tablicy zawierającej co najmniej 2 obiektyLatLng
. samples
(wymagany) określa liczbę przykładowych punktów na ścieżce, do których mają być zwracane dane wysokości. Parametrsamples
dzieli podany argumentpath
na uporządkowany zestaw równoważnych punktów na ścieżce.
Tak jak w przypadku żądań pozycjonowania, parametr path
określa zestaw szerokości i długości geograficznej. W przeciwieństwie do żądania pozycjonującego path
określa jednak uporządkowany zestaw wierzchołków. Zamiast zwracać dane o wysokości na wierzchołkach, żądania próbek ścieżek są próbkowane wzdłuż długości ścieżki, gdzie każda próbka jest oddalona od siebie (włącznie z punktami końcowymi).
Reakcje na wysokość
W przypadku każdego prawidłowego żądania usługa Elevator powróci do zdefiniowanego wywołania zwrotnego obiektu ElevationResult
i obiektu ElevationStatus
.
Stany wysokości
Każde żądanie wysokości zwraca kod ElevationStatus
w funkcji wywołania zwrotnego. Kod status
zawiera jedną z tych wartości:
OK
wskazuje, że żądanie usługi zostało zrealizowane- Wartość
INVALID_REQUEST
wskazująca, że żądanie usługi było uszkodzone OVER_QUERY_LIMIT
wskazuje, że żądający przekroczył limitREQUEST_DENIED
wskazuje, że usługa nie zakończyła żądania, prawdopodobnie z powodu nieprawidłowego parametruUNKNOWN_ERROR
oznacza nieznany błąd
Aby sprawdzić, czy wywołanie zwrotne zostało zrealizowane, przeanalizuj ten kod stanu w: OK
.
Wyniki wzniesienia
Po sukcesie argument results
Twojej funkcji wywołania zwrotnego będzie zawierać zbiór obiektów ElevationResult
.
Obiekty te zawierają następujące elementy:
- Element
location
(zawierający obiektyLatLng
) pozycji, dla której obliczane są dane o wysokości. Pamiętaj, że w przypadku żądań ścieżki zestaw elementówlocation
będzie zawierał punkty na ścieżce. - Element
elevation
wskazujący wysokość w metrach. - Wartość
resolution
wskazująca maksymalną odległość w metrach między punktami danych, w których nastąpiła interpolacja wysokości. Jeśli ta rozdzielczość nie jest znana, nie będzie tej właściwości. Pamiętaj, że dane o wzniesieniu stają się bardziej przybliżone (większe wartościresolution
), gdy przekazywanych jest wiele punktów. Aby uzyskać najdokładniejszą wartość wysokości punktu, należy je wysyłać niezależnie.
Przykłady wysokości
Ten kod przekształca kliknięcie mapy w żądanie wysokości, używając obiektu LocationElevationRequest
:
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;
Fragment
Poniższy przykład pokazuje tworzenie łamanej na podstawie zestawu współrzędnych i wyświetlanie danych wysokości na tej ścieżce za pomocą interfejsu
GoogleWizualizacj API. Ten interfejs API musisz wczytać za pomocą Google Load Loader. Prośba o wzniesienie jest tworzona za pomocą PathElevationRequest
:
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;