Prośby o zmianę wysokości i odpowiedzi

Żądania dotyczące wysokości

Żądania do interfejsu Elevation API są tworzone jako ciąg znaków adresu URL. Interfejs API zwraca dane o wysokości w różnych miejscach na świecie. Dane o lokalizacji możesz określić na 2 sposoby:

• jako zbiór co najmniej 1 locations.
• jako seria połączonych punktów wzdłuż path.

Oba te podejścia wykorzystują współrzędne geograficzne do identyfikowania lokalizacji lub wierzchołków ścieżki. W tym dokumencie opisujemy wymagany format adresów URL interfejsu Elevation API i dostępne parametry.

Interfejs Elevation API zwraca dane dla zapytań dotyczących pojedynczych punktów z największą możliwą dokładnością. Zapytania wsadowe obejmujące wiele lokalizacji mogą zwracać mniej dokładne dane, zwłaszcza jeśli lokalizacje są od siebie oddalone, ponieważ następuje pewne wygładzanie danych.

Żądanie interfejsu Elevation API ma następującą formę:

https://maps.googleapis.com/maps/api/elevation/outputFormat?parameters

gdzie outputFormat może mieć jedną z tych wartości:

• json (zalecane) – wskazuje dane wyjściowe w formacie JavaScript Object Notation (JSON);
• xml oznacza dane wyjściowe w formacie XML, zawarte w węźle <ElevationResponse>.

Uwaga: aby adresy URL były prawidłowe, muszą być odpowiednio zakodowane. W przypadku wszystkich usług internetowych obowiązuje limit 16 384 znaków. Pamiętaj o tym ograniczeniu podczas tworzenia adresów URL. Różne przeglądarki, serwery proxy i serwery mogą mieć też różne limity znaków w adresie URL.

W przypadku żądań, które używają klucza interfejsu API, wymagany jest protokół HTTPS.

Parametry żądania

Żądania wysyłane do interfejsu Elevation API wykorzystują różne parametry w zależności od tego, czy dotyczą dyskretnych lokalizacji, czy uporządkowanej ścieżki. W przypadku dyskretnych lokalizacji żądania wysokości zwracają dane dotyczące konkretnych lokalizacji przekazanych w żądaniu. W przypadku ścieżek żądania wysokości są próbkowane wzdłuż danej ścieżki.

Zgodnie ze standardem obowiązującym w przypadku wszystkich adresów URL parametry są rozdzielane znakiem ampersand (&). Listę parametrów i ich możliwych wartości znajdziesz poniżej.

Wszystkie prośby

• key – (wymagany) klucz interfejsu API aplikacji. Ten klucz identyfikuje Twoją aplikację na potrzeby zarządzania limitami. Dowiedz się, jak uzyskać klucz.

Żądania dotyczące pozycji

• locations (wymagany) określa lokalizacje na Ziemi, z których mają być zwracane dane o wysokości. Ten parametr przyjmuje pojedynczą lokalizację jako parę {szerokość geograficzna,długość geograficzna} oddzieloną przecinkiem (np. „40.714728,-73.998672”) lub wiele par szerokości i długości geograficznej przekazywanych jako tablica lub zakodowana linia łamana. W przypadku tego parametru obowiązuje limit 512 punktów. Więcej informacji znajdziesz w sekcji Określanie lokalizacji poniżej.

Żądania ścieżki próbkowanej

• path (wymagany) określa ścieżkę na Ziemi, dla której mają być zwracane dane o wysokości. Ten parametr definiuje zbiór co najmniej 2 uporządkowanych par {szerokość geograficzna,długość geograficzna} określających ścieżkę na powierzchni Ziemi. Ten parametr musi być używany w połączeniu z parametrem samples opisanym poniżej. W przypadku tego parametru obowiązuje limit 512 punktów. Więcej informacji znajdziesz w sekcji Określanie ścieżek poniżej.
• samples (wymagany) określa liczbę punktów próbnych na ścieżce, dla których mają być zwracane dane o wysokości. Parametr samples dzieli podaną wartość path na uporządkowany zbiór równoodległych punktów wzdłuż ścieżki.

Określanie lokalizacji

Żądania dotyczące pozycji są oznaczane za pomocą parametru locations, który wskazuje żądania dotyczące wysokości dla konkretnych lokalizacji przekazywanych jako wartości szerokości i długości geograficznej.

Parametr locations może przyjmować te argumenty:

• pojedyncze współrzędne: locations=40.714728,-73.998672,
• Tablica współrzędnych rozdzielonych znakiem kreski pionowej („|”):locations=40.714728,-73.998672|-34.397,150.644
• Zestaw zakodowanych współrzędnych za pomocą algorytmu kodowania linii łamanych: locations=enc:gfo}EtohhU

Ciągi współrzędnych geograficznych są definiowane za pomocą cyfr w ciągu tekstowym oddzielonym przecinkami. Na przykład „40.714728,-73.998672” jest prawidłową wartością locations. Wartości szerokości i długości geograficznej muszą odpowiadać prawidłowej lokalizacji na powierzchni Ziemi. Szerokość geograficzna może przyjmować dowolną wartość z przedziału od -90 do 90, a długość geograficzna – dowolną wartość z przedziału od -180 do 180. Jeśli podasz nieprawidłową wartość szerokości lub długości geograficznej, Twoje żądanie zostanie odrzucone jako nieprawidłowe.

W tablicy lub zakodowanej polilinii możesz przekazać maksymalnie 512 współrzędnych, zachowując przy tym prawidłowy adres URL. Pamiętaj, że w przypadku przekazywania wielu współrzędnych dokładność zwracanych danych może być mniejsza niż w przypadku żądania danych dla pojedynczych współrzędnych. Przekroczenie 512 punktów lub współrzędnych w parametrach „locations” lub „path” zwraca odpowiedź INVALID_REQUEST.

Określanie ścieżek

Żądania ścieżek próbkowanych są oznaczane za pomocą parametrów path i samples, co oznacza żądanie danych o wysokości wzdłuż ścieżki w określonych odstępach. Podobnie jak w przypadku żądań dotyczących pozycji, w których używany jest parametr locations, parametr path określa zestaw wartości szerokości i długości geograficznej. W odróżnieniu od żądania pozycyjnego path określa uporządkowany zbiór wierzchołków. Zamiast zwracać dane o wysokości tylko w wierzchołkach, żądania dotyczące ścieżki są próbkowane wzdłuż ścieżki na podstawie podanej liczby samples (włącznie z punktami końcowymi).

Parametr path może przyjmować te argumenty:

• Tablica zawierająca co najmniej 2 ciągi tekstowe z współrzędnymi rozdzielone przecinkami, a następnie znakiem „|”: path=40.714728,-73.998672|-34.397,150.644
• Zakodowane współrzędne za pomocą algorytmu kodowania linii łamanych: path=enc:gfo}EtohhUxD@bAxJmGF

Ciągi współrzędnych geograficznych są definiowane za pomocą cyfr w ciągu tekstowym oddzielonym przecinkami. Na przykład „40.714728,-73.998672|-34.397, 150.644” to prawidłowa wartość.path Wartości szerokości i długości geograficznej muszą odpowiadać prawidłowej lokalizacji na powierzchni Ziemi. Szerokość geograficzna może przyjmować dowolną wartość z przedziału od -90 do 90, a długość geograficzna – dowolną wartość z przedziału od -180 do 180. Jeśli podasz nieprawidłową wartość szerokości lub długości geograficznej, Twoje żądanie zostanie odrzucone jako nieprawidłowe.

W tablicy lub zakodowanej polilinii możesz przekazać maksymalnie 512 współrzędnych, zachowując przy tym prawidłowy adres URL. Pamiętaj, że w przypadku przekazywania wielu współrzędnych dokładność zwracanych danych może być mniejsza niż w przypadku żądania danych dla pojedynczych współrzędnych. Przekroczenie 512 punktów lub współrzędnych w parametrach „locations” lub „path” zwraca odpowiedź INVALID_REQUEST.

Odpowiedzi dotyczące wysokości

W przypadku każdego prawidłowego żądania usługa Elevation zwraca odpowiedź Elevation w formacie wskazanym w adresie URL żądania.

Jeśli kod stanu jest inny niż OK, w obiekcie odpowiedzi Elevation może się pojawić dodatkowe pole error_message. To pole zawiera bardziej szczegółowe informacje o przyczynach danego kodu stanu.

Odpowiedź zawiera tablicę results z tymi elementami:

Obiekt location ma te elementy:

Przykłady wysokości względnej

Poniższy przykład wysyła żądanie wysokości nad poziomem morza dla Denver w Kolorado, czyli „Miasta na wysokości mili”, w formacie JSON:

https://maps.googleapis.com/maps/api/elevation/json
  ?locations=39.7391536%2C-104.9847034
  &key=YOUR_API_KEY

curl -L -X GET 'https://maps.googleapis.com/maps/api/elevation/json?locations=39.7391536%2C-104.9847034&key=YOUR_API_KEY'

{
  "results":
    [
      {
        "elevation": 1608.637939453125,
        "location": { "lat": 39.7391536, "lng": -104.9847034 },
        "resolution": 4.771975994110107,
      },
    ],
  "status": "OK",
}

<ElevationResponse>
 <status>OK</status>
 <result>
  <location>
   <lat>39.7391536</lat>
   <lng>-104.9847034</lng>
  </location>
  <elevation>1608.6379395</elevation>
  <resolution>4.7719760</resolution>
 </result>
</ElevationResponse>

Poniższy przykład pokazuje kilka odpowiedzi (dla Denver w stanie Kolorado i Dolina Śmierci w stanie Kalifornia).

To żądanie pokazuje użycie flagi JSON output:

https://maps.googleapis.com/maps/api/elevation/json
  ?locations=39.7391536%2C-104.9847034%7C36.455556%2C-116.866667
  &key=YOUR_API_KEY

curl -L -X GET 'https://maps.googleapis.com/maps/api/elevation/json?locations=39.7391536%2C-104.9847034%7C36.455556%2C-116.866667&key=YOUR_API_KEY'

To żądanie pokazuje użycie flagi XML output:

https://maps.googleapis.com/maps/api/elevation/xml?locations=39.7391536,-104.9847034|36.455556,-116.866667&key=YOUR_API_KEY

Aby zobaczyć przykładowe odpowiedzi w formatach JSON i XML, wybierz karty poniżej.

{
  "results":
    [
      {
        "elevation": 1608.637939453125,
        "location": { "lat": 39.7391536, "lng": -104.9847034 },
        "resolution": 4.771975994110107,
      },
      {
        "elevation": -52.79492568969727,
        "location": { "lat": 36.455556, "lng": -116.866667 },
        "resolution": 19.08790397644043,
      },
    ],
  "status": "OK",
}

<ElevationResponse>
 <status>OK</status>
 <result>
  <location>
   <lat>39.7391536</lat>
   <lng>-104.9847034</lng>
  </location>
  <elevation>1608.6379395</elevation>
  <resolution>4.7719760</resolution>
 </result>
 <result>
  <location>
   <lat>36.4555560</lat>
   <lng>-116.8666670</lng>
  </location>
  <elevation>-52.7949257</elevation>
  <resolution>19.0879040</resolution>
 </result>
</ElevationResponse>

W przykładach poniżej wysyłamy żądania danych o wysokości wzdłuż linii prostejpath od Mt. Whitney w Kalifornii do Badwater w Kalifornii, czyli od najwyższego do najniższego punktu w kontynentalnej części Stanów Zjednoczonych. Prosimy o 3 punktysamples, czyli 2 punkty końcowe i punkt w połowie odcinka.

https://maps.googleapis.com/maps/api/elevation/json
  ?path=36.578581%2C-118.291994%7C36.23998%2C-116.83171
  &samples=3
  &key=YOUR_API_KEY

curl -L -X GET 'https://maps.googleapis.com/maps/api/elevation/json?path=36.578581%2C-118.291994%7C36.23998%2C-116.83171&samples=3&key=YOUR_API_KEY'

{
  "results":
    [
      {
        "elevation": 4411.94189453125,
        "location": { "lat": 36.578581, "lng": -118.291994 },
        "resolution": 19.08790397644043,
      },
      {
        "elevation": 1372.8359375,
        "location": { "lat": 36.41150289067028, "lng": -117.5602607523847 },
        "resolution": 9.543951988220215,
      },
      {
        "elevation": -84.51690673828125,
        "location": { "lat": 36.23998, "lng": -116.83171 },
        "resolution": 9.543951988220215,
      },
    ],
  "status": "OK",
}

<ElevationResponse>
 <status>OK</status>
 <result>
  <location>
   <lat>36.5785810</lat>
   <lng>-118.2919940</lng>
  </location>
  <elevation>4411.9418945</elevation>
  <resolution>19.0879040</resolution>
 </result>
 <result>
  <location>
   <lat>36.4115029</lat>
   <lng>-117.5602608</lng>
  </location>
  <elevation>1372.8359375</elevation>
  <resolution>9.5439520</resolution>
 </result>
 <result>
  <location>
   <lat>36.2399800</lat>
   <lng>-116.8317100</lng>
  </location>
  <elevation>-84.5169067</elevation>
  <resolution>9.5439520</resolution>
 </result>
</ElevationResponse>