Prośby o zmianę wysokości i odpowiedzi

Prośby o potwierdzenie poziomu

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

  • jako zestaw zawierający co najmniej jeden element locations.
  • Jako seria połączonych punktów wzdłuż path.

W obu tych podejściach 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ć mniej dokładne dane, zwłaszcza jeśli lokalizacje są od siebie oddalone, ponieważ dane są wygładzane.

Żą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 (zalecany) – wskazuje dane wyjściowe w formacie JavaScript Object Notation (JSON);
  • xml, wskazuje dane wyjściowe w formacie XML, opakowane w węzeł <ElevationResponse>.

Uwaga: aby adresy URL były prawidłowe, muszą być odpowiednio zakodowane. W przypadku wszystkich usług internetowych ich długość 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 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 wysyłane do interfejsu Elevation API wykorzystują różne parametry w zależności od tego, czy dotyczą pojedynczych lokalizacji czy uporządkowanej ścieżki. W przypadku pojedynczych 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 (&amp;). Lista parametrów i ich możliwych wartości znajduje się 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 pozycyjne

  • locations (wymagany) określa lokalizacje na Ziemi, dla których mają zostać zwrócone dane o wysokości. Ten parametr przyjmuje pojedynczą lokalizację jako parę {szerokość,długość} rozdzieloną przecinkami (np. „40.714728,-73.998672”) lub wiele par szerokości i długości geograficznej przekazanych jako tablica lub zakodowana linia łamana. Ten parametr ma limit 512 punktów. Więcej informacji znajdziesz poniżej w sekcji Określanie lokalizacji.

Przykładowe żądania ścieżki

  • path (wymagany) definiuje ścieżkę na Ziemi, dla której mają zostać zwrócone dane o wysokości. Ten parametr określa zbiór co najmniej 2 uporządkowanych par {szerokość,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. Ten parametr ma 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 na ścieżce, dla których mają zostać zwrócone dane o wysokości. Parametr samples dzieli dany element 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 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:

  • Pojedyncza 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 przy użyciu algorytmu zakodowanej 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” jest prawidłową wartością 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 – 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 gdy przekazujesz wiele współrzędnych, dokładność zwracanych danych może być niższa niż w przypadku żądania danych dotyczących pojedynczych współrzędnych. Przekroczenie 512 punktów lub współrzędnych w parametrach „locations” lub „path” powoduje zwrócenie odpowiedzi INVALID_REQUEST.

Określ ścieżki

Żądania ścieżki z próbkowaniem są wskazywane przez użycie parametrów path i samples, które oznaczają żądanie danych o wysokości wzdłuż ścieżki w określonych odstępach czasu. Podobnie jak w przypadku żądań pozycyjnych, które używają parametru locations, parametr path określa zestaw wartości szerokości i długości geograficznej. Jednak 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 ścieżki są próbkowane wzdłuż długości ścieżki na podstawie określonej liczby samples (w tym punktów końcowych).

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

  • Tablica zawierająca co najmniej 2 ciągi tekstowe współrzędnych rozdzielone przecinkami i znakiem kreski pionowej („|”): path=40.714728,-73.998672|-34.397,150.644
  • Współrzędne zakodowane za pomocą algorytmu kodowania 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 rozdzielonym przecinkami. 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 kuli ziemskiej. Szerokość geograficzna może mieć dowolną wartość z zakresu od -90 do 90, a długość geograficzna – z zakresu 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 gdy przekazujesz wiele współrzędnych, dokładność zwracanych danych może być niższa niż w przypadku żądania danych dotyczących pojedynczych współrzędnych. Przekroczenie 512 punktów lub współrzędnych w parametrach „locations” lub „path” powoduje zwrócenie odpowiedzi INVALID_REQUEST.

Odpowiedzi dotyczące wysokości

  • Tablica zawierająca co najmniej 2 ciągi tekstowe współrzędnych rozdzielone przecinkami i znakiem kreski pionowej („|”): path=40.714728,-73.998672|-34.397,150.644
  • Współrzędne zakodowane za pomocą algorytmu kodowania 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 rozdzielonym przecinkami. 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 kuli ziemskiej. Szerokość geograficzna może mieć dowolną wartość z zakresu od -90 do 90, a długość geograficzna – z zakresu 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 gdy przekazujesz wiele współrzędnych, dokładność zwracanych danych może być niższa niż w przypadku żądania danych dotyczących pojedynczych współrzędnych. Przekroczenie 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

Pole Wymagane Typ Opis
wymagane Array<ElevationResult> Więcej informacji znajdziesz w sekcji ElevationResult.
wymagane ElevationStatus Więcej informacji znajdziesz w artykule ElevationStatus.
opcjonalnie tekst

Gdy usługa zwraca kod stanu inny niż OK, w obiekcie odpowiedzi może znajdować się dodatkowe pole error_message. To pole zawiera bardziej szczegółowe informacje o przyczynach danego kodu stanu. To pole nie zawsze jest zwracane, a jego zawartość może ulec zmianie.

ElevationStatus

Kody stanu zwracane przez usługę.

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

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

Odpowiedź zawiera tablicę results z tymi elementami:

ElevationResult

Pole Wymagane Typ Opis
wymagane liczba

Wysokość lokalizacji w metrach.
wymagane LatLngLiteral

Element lokalizacji pozycji, dla której obliczane są dane wysokości. Pamiętaj, że w przypadku żądań ścieżki zbiór elementów lokalizacji będzie zawierać próbkowane punkty na ścieżce.

Więcej informacji znajdziesz w artykule LatLngLiteral.

opcjonalnie liczba

Wartość wskazująca maksymalną odległość między punktami danych, z których interpolowano wysokość, w metrach. Jeśli rozdzielczość jest nieznana, ta właściwość nie będzie dostępna. Pamiętaj, że dane o wysokości stają się mniej dokładne (większe wartości rozdzielczości), gdy przekazywanych jest wiele punktów. Aby uzyskać jak najdokładniejszą wartość wysokości dla danego punktu, należy wysłać zapytanie niezależnie.

LatLngLiteral

Obiekt opisujący konkretną lokalizację z szerokością i długością geograficzną w stopniach dziesiętnych.

Pole Wymagane Typ Opis
wymagane liczba

Szerokość geograficzna w stopniach dziesiętnych
wymagane liczba

Długość geograficzna w stopniach dziesiętnych

Przykłady wysokości pozycyjnej

Ten przykładowy kod wysyła żądanie o wysokość nad poziomem morza dla Denver w Kolorado, czyli „Mile High City”:

URL

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

cURL

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

JSON

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

XML

        
<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 Kolorado i Doliny Śmierci w Kalifornii).

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

URL

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

cURL

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 XML output:

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

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

JSON

      
{
  "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",
}

XML

      
<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 żądane są dane o wysokości wzdłuż linii prostej path od góry Whitney w Kalifornii do Badwater w Kalifornii, czyli najwyższego i najniższego punktu w kontynentalnej części Stanów Zjednoczonych. Prosimy o 3 samples, więc będą to 2 punkty końcowe i punkt środkowy.

URL

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

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'

JSON

      
{
  "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",
}

XML

      
<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>