Prośby o zmianę wysokości i odpowiedzi

Prośby o podniesienie wysokości

Żądania do interfejsu Elevation API są tworzone jako ciąg adresu URL. API zwraca dane o wysokości względnej lokalizacji na Ziemi. Dane o lokalizacji określa się na jeden z dwóch sposobów:

• Jako zbiór zawierający co najmniej 1 locations.
• Jako seria połączonych punktów na cieśninie path.

W każdej z tych metod do identyfikowania lokalizacji lub wierzchołków ścieżek używane są współrzędne długości i szerokości geograficznej. W tym dokumencie opisujemy wymagany format adresów URL interfejsu Elevation API i dostępne parametry.

Interfejs Elevation API zwraca dane dla zapytań jednopunktowych z największą możliwą dokładnością. Zapytania zbiorcze obejmujące wiele lokalizacji mogą zwracać dane z mniej dokładnością, zwłaszcza jeśli lokalizacje są od siebie rozłożone, ponieważ następuje pewne wygładzanie danych.

Żądanie do interfejsu Elevation API ma taką postać:

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

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

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

Uwaga: prawidłowe adresy URL muszą być odpowiednio zakodowane, a ich długość we wszystkich usługach internetowych jest ograniczona do 16 384 znaków. Pamiętaj o tym limicie podczas tworzenia adresów URL. Pamiętaj, że różne przeglądarki, serwery proxy i serwery również mogą mieć różne limity znaków adresu URL.

W przypadku żądań korzystających z klucza interfejsu API wymagany jest protokół HTTPS.

Parametry żądania

Żądania do interfejsu Elevation API używają różnych parametrów w zależności od tego, czy żądanie dotyczy konkretnych lokalizacji, czy uporządkowanej ścieżki. W przypadku dyskretnych lokalizacji żądania danych o wzniesieniu wysokości dotyczące konkretnych lokalizacji przekazane w żądaniu są przekazywane. W przypadku ścieżek żądania podniesienia uprawnień są próbkowane wzdłuż określonej ścieżki.

Standardowo we wszystkich adresach URL parametry są oddzielane znakiem „&”. Poniżej znajdziesz listę parametrów i ich możliwych wartości.

Wszystkie prośby

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

Żądania pozycjonowania

• locations (wymagany) określa lokalizacje na Ziemi, z których mają być zwracane dane o wysokości. Ten parametr przyjmuje jedną lokalizację w postaci rozdzielonej przecinkami pary {szerokość,długość} (np. „40.714728,-73.998672”) lub wiele par szerokości i długości geograficznej przekazywanych w postaci tablicy lub w postaci zakodowanej linii łamanej. Ten konkretny parametr ma limit 512 punktów. Więcej informacji znajdziesz w sekcji Określanie lokalizacji poniżej.

Próbkowane żądania ścieżek

• path (wymagany) określa ścieżkę na Ziemi, dla której zwracają dane o wysokości. Ten parametr określa zestaw co najmniej dwóch uporządkowanych par {width,longitude}, które określają ścieżkę wzdłuż powierzchni Ziemi. Tego parametru należy używać w połączeniu z parametrem samples opisanym poniżej. Ten konkretny parametr może mieć maksymalnie 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 na ścieżce.

Określanie lokalizacji

Żądania pozycji są wskazywane za pomocą parametru locations, który wskazuje żądania wysokości względnej dla określonych lokalizacji przekazywane jako wartości szerokości i długości geograficznej.

Parametr locations może przyjmować te argumenty:

• Jedna współrzędna: locations=40.714728,-73.998672
• Tablica współrzędnych rozdzielonych pionową kreską („|”): locations=40.714728,-73.998672|-34.397,150.644
• Zestaw zakodowanych współrzędnych za pomocą zakodowanego algorytmu linii łamanej: locations=enc:gfo}EtohhU

Ciągi współrzędnych szerokości i długości geograficznej są definiowane za pomocą cyfr w ciągu tekstowym rozdzielanym przecinkami. Na przykład „40.714728,-73.998672” to prawidłowa wartość locations. Wartości szerokości i długości geograficznej muszą odpowiadać prawidłowej lokalizacji na kuli ziemskiej. Szerokość geograficzna może mieć dowolną wartość z zakresu od -90 do 90, a długość geograficzna – dowolną wartość z zakresu od -180 do 180. Jeśli podasz nieprawidłową wartość szerokości lub długości geograficznej, żądanie zostanie odrzucone jako błędne.

W tablicy lub zakodowanej linii łamanej można przekazać do 512 współrzędnych, nadal tworząc 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 jednej współrzędnej. Przekroczenie 512 punktów lub współrzędnych w parametrach „locations” lub „path” powoduje zwrócenie odpowiedzi INVALID_REQUEST.

Określanie ścieżek

Próbkowane żądania ścieżek są wskazywane za pomocą parametrów path i samples, co wskazuje na żądanie danych o wzroście wysokości na ścieżce w określonych odstępach czasu. Tak jak w przypadku żądań położenia korzystających z parametru locations, parametr path określa zestaw wartości szerokości i długości geograficznej. Jednak w przeciwieństwie do żądania pozycjonowania path określa uporządkowany zestaw wierzchołków. Zamiast zwracać dane o wysokości tylko w wierzchołkach, żądania ścieżki są próbkowane wzdłuż długości ścieżki na podstawie określonej liczby wartości samples (włącznie z punktami końcowymi).

Parametr path może przyjmować jeden z tych argumentów:

• Tablica z co najmniej 2 ciągami tekstowymi współrzędnych rozdzielonych przecinkami, które są rozdzielone pionową kreską („|”): path=40.714728,-73.998672|-34.397,150.644
• Współrzędne zakodowane za pomocą kodowanego algorytmu linii łamanej: path=enc:gfo}EtohhUxD@bAxJmGF

Ciągi współrzędnych szerokości i długości geograficznej są definiowane za pomocą cyfr w ciągu tekstowym rozdzielanym 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 kuli ziemskiej. Szerokość geograficzna może mieć dowolną wartość z zakresu od -90 do 90, a długość geograficzna – dowolną wartość z zakresu od -180 do 180. Jeśli podasz nieprawidłową wartość szerokości lub długości geograficznej, żądanie zostanie odrzucone jako błędne.

W tablicy lub zakodowanej linii łamanej można przekazać do 512 współrzędnych, nadal tworząc prawidłowy adres URL. Pamiętaj, że w przypadku przekazywania wielu współrzędnych dokładność zwróconych danych może być niższa niż w przypadku żądania danych dla jednej współrzędnej. Przekroczenie 512 punktów lub współrzędnych w parametrze „locations” (lokalizacja) lub „path” (ścieżka) zwraca odpowiedź INVALID_REQUEST.

Odpowiedzi dotyczące wysokości

W przypadku każdego prawidłowego żądania usługa wysokości względnej zwróci odpowiedź dotyczącą wysokości w formacie wskazanym w adresie URL żądania.

Gdy kod stanu jest inny niż OK, w obiekcie odpowiedzi dotyczącej wysokości może znajdować się dodatkowe pole error_message. To pole zawiera bardziej szczegółowe informacje o przyczynach występowania danego kodu stanu.

Odpowiedź zawiera tablicę results z tymi elementami:

Obiekt location zawiera te elementy:

Przykłady pozycjonowania wysokości

Poniższy przykład wymaga podania wysokości dla Denver (Kolorado) i „Mile High City” 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 przedstawia wiele odpowiedzi (dla Denver w stanie Kolorado i Doliny Śmierci w Kalifornii).

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

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 demonstruje użycie flagi output XML:

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

Kliknij karty poniżej, aby zobaczyć przykładowe odpowiedzi JSON i XML.

{
  "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 poniższych przykładach wymagane jest podanie danych o wysokości względnej wzdłuż linii prostej path z Mount Whitney w Kalifornii do Badwater w Kalifornii oraz najwyższego i najniższego punktu kontynentalnej części Stanów Zjednoczonych. Potrzebujemy 3 elementów samples, aby uwzględnić 2 punkty końcowe i połowę drogi.

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>