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 o mniejszej 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) – wskazuje dane wyjściowe w formacie JavaScript Object Notation (JSON);
  • xml – wskazuje 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 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 we wszystkich adresach URL parametry są rozdzielane znakiem ampersand (&amp;). 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 limitem. 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} rozdzieloną 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 dotyczące próbkowanej ś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 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 wskazuje żądania 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 ciągu tekstowym rozdzielonym przecinkami. 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 wskazują żą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 ścieżki są próbkowane wzdłuż ścieżki na podstawie liczby samples określonych (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 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 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 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 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

Pole Wymagane Typ Opis
wymagane Array<ElevationResult> Więcej informacji znajdziesz w sekcji ElevationResult.
wymagane ElevationStatus Więcej informacji znajdziesz w sekcji ElevationStatus.
opcjonalnie ciąg znaków

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

ElevationStatus

Kody stanu zwracane przez usługę.

  • OK – żądanie do interfejsu API zostało zrealizowane.
  • DATA_NOT_AVAILABLE – brak dostępnych danych dla lokalizacji wejściowych.
  • INVALID_REQUEST – żądanie do interfejsu API jest nieprawidłowe.
  • OVER_DAILY_LIMIT – przekroczono dzienny limit.
    • 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 – przekroczono limit zapytań.
  • 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

Pole Wymagane Typ Opis
wymagane liczba

Wysokość lokalizacji w metrach.
wymagane LatLngLiteral

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

Więcej informacji znajdziesz w sekcji LatLngLiteral.

opcjonalnie liczba

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

LatLngLiteral

Obiekt opisujący konkretną lokalizację za pomocą szerokości i długości geograficznej 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 dotyczące wysokości

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

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>

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:

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

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>

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

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>