Prośby o zmianę wysokości i odpowiedzi

Prośby o potwierdzenie wysokości

Żądania do interfejsu Elevation API są tworzone jako ciąg znaków 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 lokalizacji locations;
• jako serię połączonych punktów wzdłuż path.

W obu przypadkach do identyfikowania lokalizacji lub wierzchołków ścieżki używane są współrzędne geograficzne. W tym dokumencie opisujemy wymagany format adresów URL interfejsu Elevation API oraz dostępne parametry.

Interfejs Elevation API zwraca dane dla zapytań o pojedynczy punkt z najwyższą możliwą dokładnością. Zapytania zbiorcze dotyczące wielu lokalizacji mogą zwracać dane z mniejszą dokładnością, zwłaszcza jeśli lokalizacje są od siebie oddalone, ponieważ następuje pewne wygładzenie danych.

Żądanie do interfejsu Elevation API ma następującą postać:

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

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

• json (zalecane) – oznacza dane wyjściowe w formacie JavaScript Object Notation (JSON);
• xml – oznacza dane wyjściowe w formacie XML, opakowane w węzeł <ElevationResponse>.

Uwaga: adresy URL muszą być prawidłowo zakodowane , aby były prawidłowe, a w przypadku wszystkich usług internetowych ich długość jest ograniczona do 16 384 znaków. Pamiętaj o tym ograniczeniu podczas tworzenia adresów URL. Pamiętaj też, że różne przeglądarki, serwery proxy i serwery mogą mieć różne limity znaków w adresach URL.

W przypadku żądań, które używają 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 dyskretnych lokalizacji, czy uporządkowanej ścieżki. W przypadku dyskretnych lokalizacji żądania dotyczące wysokości zwracają dane o konkretnych lokalizacjach przekazanych w żądaniu. W przypadku ścieżek żądania dotyczące wysokości są próbkowane wzdłuż danej ścieżki.

Zgodnie ze standardem we wszystkich adresach URL parametry są rozdzielane znakiem ampersand (&). 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 dotyczące pozycji

• locations (wymagany) określa lokalizacje na świecie, z których mają być zwracane dane o wysokości. Ten parametr przyjmuje pojedynczą lokalizację jako rozdzieloną przecinkami parę {szerokość geograficzna,długość geograficzna} (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 dotyczące próbkowanej ścieżki

• path (wymagany) określa ścieżkę na świecie, dla której mają być zwracane dane o wysokości. Ten parametr określa zbiór co najmniej 2 uporządkowanych par {szerokość geograficzna,długość geograficzna} definiują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óbkowania wzdłuż ścieżki, dla których mają być zwracane dane o wysokości. Parametr samples dzieli daną path na uporządkowany zbiór równoodległych punktów wzdłuż ścieżki.

Określanie lokalizacji

Żądania dotyczące pozycji są wskazywane przez użycie parametru locations, który określa żą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 pionową kreską ('|') character: locations=40.714728,-73.998672|-34.397,150.644
• Zbiór zakodowanych współrzędnych za pomocą algorytmu kodowania linii łamanych: locations=enc:gfo}EtohhU

Ciągi znaków współrzędnych szerokości i długości geograficznej są definiowane za pomocą cyfr w rozdzielonym przecinkami ciągu tekstowym. Na przykład „40.714728,-73.998672” jest prawidłową wartością parametru 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 zakresu od -90 do 90, a długość geograficzna – 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 linii łamanej 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 limitu 512 punktów lub współrzędnych w parametrach „locations” lub „path” powoduje zwrócenie odpowiedzi INVALID_REQUEST.

Określanie ścieżek

Żądania dotyczące próbkowanej ścieżki są wskazywane przez użycie parametrów path i samples, które określają żądanie danych o wysokości wzdłuż ścieżki w określonych odstępach. Podobnie jak w przypadku żądań dotyczących pozycji używających parametru locations, parametr path określa zbiór wartości szerokości i długości geograficznej. W przeciwieństwie jednak do żądania dotyczącego pozycji parametr 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 określonej liczby samples (w tym punktów końcowych).

Parametr path może przyjmować te argumenty:

• Tablica co najmniej 2 ciągów tekstowych współrzędnych rozdzielonych przecinkami i pionową kreską ('|'): 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 znaków współrzędnych szerokości i długości geograficznej są definiowane za pomocą cyfr w rozdzielonym przecinkami ciągu tekstowym. Na przykład „40.714728,-73.998672|-34.397, 150.644” jest prawidłową wartością parametru 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 zakresu od -90 do 90, a długość geograficzna – 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 linii łamanej 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 limitu 512 punktów lub współrzędnych w parametrach „locations” lub „path” powoduje zwrócenie odpowiedzi INVALID_REQUEST.

Odpowiedzi dotyczące wysokości

• Tablica co najmniej 2 ciągów tekstowych współrzędnych rozdzielonych przecinkami i pionową kreską ('|'): 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 znaków współrzędnych szerokości i długości geograficznej są definiowane za pomocą cyfr w rozdzielonym przecinkami ciągu tekstowym. Na przykład „40.714728,-73.998672|-34.397, 150.644” jest prawidłową wartością parametru 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 zakresu od -90 do 90, a długość geograficzna – 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 linii łamanej 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 limitu 512 punktów lub współrzędnych w parametrach „locations” lub „path” powoduje zwrócenie odpowiedzi INVALID_REQUEST.

Odpowiedzi dotyczące wysokości

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

ElevationResponse

ElevationStatus

Kody stanu zwracane przez usługę.

• OK – żądanie do interfejsu API zostało zrealizowane.
• DATA_NOT_AVAILABLE – brak dostępnych danych dla podanych lokalizacji.
• INVALID_REQUEST – żądanie do interfejsu API jest nieprawidłowe.
• OVER_DAILY_LIMIT – wystąpiła jedna z tych sytuacji:
  • Brak klucza interfejsu API lub jest on nieprawidłowy.
  • Na koncie nie włączono płatności.
  • Przekroczono samodzielnie nałożony limit użycia.
  • Podana forma płatności jest już nieważna (np. karta kredytowa straciła ważność).
• OVER_QUERY_LIMIT – osoba wysyłająca żądanie przekroczyła limit.
• REQUEST_DENIED – interfejs API nie zrealizował żądania.
• UNKNOWN_ERROR – wystąpił nieznany błąd.

Gdy 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 podania danego kodu stanu.

Odpowiedź zawiera tablicę results z tymi elementami:

ElevationResult

LatLngLiteral

Obiekt opisujący konkretną lokalizację za pomocą szerokości i długości geograficznej w stopniach dziesiętnych.

Przykłady żądań dotyczących wysokości

Ten przykład pokazuje, jak wysłać żądanie dotyczące wysokości w Denver w stanie Kolorado, czyli w „Mieście na wysokości mili”:

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>
        
        

Ten przykład pokazuje kilka odpowiedzi (dla Denver w stanie Kolorado i Doliny Śmierci w stanie Kalifornia).

To żądanie pokazuje, jak używać flagi output w formacie 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 pokazuje, jak używać flagi output w formacie XML:

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 formacie JSON i XML, kliknij 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>
      
      

Te przykłady pokazują, jak wysłać żądanie danych o wysokości wzdłuż prostej linii path od góry Whitney w Kalifornii do Badwater w Kalifornii, czyli od najwyższego i najniższego punktu w kontynentalnej części Stanów Zjednoczonych. Prosimy o 3 samples, które będą obejmować 2 punkty końcowe i punkt środkowy.

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>