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 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. 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 wykorzystują różne parametry w zależności od tego, czy dotyczą 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 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.

Przykładowe żądania ścieżki

• path (wymagany) określa ścieżkę na Ziemi, 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 samplesopisanym 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ą zostać zwrócone dane o wysokości. Parametr samples dzieli podaną path na uporządkowany zbiór równoodległych punktów wzdłuż ścieżki.

Określanie lokalizacji

Żądania dotyczące pozycji są wskazywane za pomocą parametru locations, który oznacza żą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 przy użyciu algorytmu zakodowanej linii łamanej: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 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 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ć jeden z tych argumentów:

• Tablica co najmniej 2 ciągów tekstowych z współrzędnymi rozdzielonych przecinkami i znakiem kreski pionowej („|”):path=40.714728,-73.998672|-34.397,150.644
• Zakodowane współrzędne za pomocą algorytmu zakodowanej linii łamanej:path=enc:gfo}EtohhUxD@bAxJmGF

Ciągi znaków 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 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 512 punktów lub współrzędnych w parametrach „locations” lub „path” zwraca odpowiedź INVALID_REQUEST.

Odpowiedzi dotyczące wysokości

• Tablica co najmniej 2 ciągów tekstowych z współrzędnymi rozdzielonych przecinkami i znakiem kreski pionowej („|”):path=40.714728,-73.998672|-34.397,150.644
• Zakodowane współrzędne za pomocą algorytmu zakodowanej linii łamanej:path=enc:gfo}EtohhUxD@bAxJmGF

Ciągi znaków 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 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 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.

ElevationResponse

ElevationStatus

Kody stanu zwracane przez usługę.

• OK, co oznacza, że żądanie do interfejsu API zostało zrealizowane.
• DATA_NOT_AVAILABLE, co oznacza, że dla podanych lokalizacji nie ma dostępnych danych.
• INVALID_REQUEST, co oznacza, że żądanie do interfejsu API było nieprawidłowe.
• OVER_DAILY_LIMIT oznaczający dowolny z tych elementów:
  • Brak klucza interfejsu API lub jest on nieprawidłowy.
  • Na Twoim koncie nie włączono płatności.
  • Przekroczono samodzielnie ustalony limit wykorzystania.
  • Podana forma płatności nie jest już ważna (np. karta kredytowa straciła ważność).
• OVER_QUERY_LIMIT – oznacza, że osoba wysyłająca żądanie przekroczyła limit.
• REQUEST_DENIED, co oznacza, że interfejs API nie zrealizował żądania.
• UNKNOWN_ERROR – nieznany błąd.

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:

ElevationResult

LatLngLiteral

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

Przykłady wysokości względnej

Ten przykład wysyła żądanie wysokości nad poziomem morza dla Denver w Kolorado, czyli „Miasta 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>
        
        

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 3samples, 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>