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. Interfejs API zwraca dane o wysokości względnej lokalizacji na Ziemi. Dane o lokalizacji możesz określić na 2 sposoby:

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

Każda z tych metod wykorzystuje współrzędne szerokości i długości geograficznej do identyfikacji lokalizacji lub wierzchołków ścieżek. W tym dokumencie opisano wymagany format Adresy 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 dotyczące wielu lokalizacji mogą zwrócić dane z mniejszą dokładnością, zwłaszcza jeśli lokalizacje są rozproszone między poszczególnymi elementami, a także wygładzać dane.

Żądanie do interfejsu Elevation API ma taką 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 JSON (JavaScript Object Notation);
• xml, wskazuje dane wyjściowe w formacie XML, opakowane w <ElevationResponse> węzeł.

Uwaga: aby URL-e były prawidłowe, muszą być prawidłowo zakodowane. Ich długość jest ograniczona do 16 384 znaków we wszystkich usługach internetowych. Pamiętaj o tym limicie podczas tworzenia adresów URL. Pamiętaj, że różne przeglądarki, serwery proxy i serwery mogą mieć też inne limity liczby znaków w adresach 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, uporządkowaną ścieżkę. W przypadku pojedynczych lokalizacji żądania dotyczące rzeźby terenu zwracają dane o konkretnych lokalizacjach przekazanych w żądaniu. W przypadku ścieżek żądania dotyczące rzeźby terenu są próbkowane wzdłuż danej ścieżki.

Zgodnie ze standardem w przypadku wszystkich adresów URL parametry są rozdzielane znakiem ampersand (&). Lista parametrów i ich możliwych wartości znajduje się poniżej.

Wszystkie prośby

• key – (wymagany) klucz 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 Ziemia, z której mają zostać zwrócone dane o wysokości. Ten parametr może przyjmować pojedynczą lokalizację jako parę {szerokość geograficzna, długość geograficzna} rozdzieloną przecinkami (np. „40.714728,-73.998672”) lub wiele par szerokości geograficznej i długości geograficznej przekazanych jako tablica lub zakodowana linia łamana. Obowiązuje limit 512 punktów. dla tego konkretnego parametru. Aby dowiedzieć się więcej, zapoznaj się z sekcją Określanie lokalizacji poniżej.

Próbkowe żądania ścieżki

• path (wymagany) definiuje ścieżkę na Ziemi, dla której mają być zwracane dane dotyczące rzeźby terenu. Ten parametr definiuje co najmniej 2 uporządkowane pary {latitude,longitude}, które określają ścieżkę na powierzchni ziemi. Ten parametr musi być używany w połączeniu z parametrem samplesopisanym poniżej. Obowiązuje limit 512 punktów. konkretnego parametru. Aby dowiedzieć się więcej, zapoznaj się z sekcją Określanie ścieżek poniżej.
• samples (wymagane) określa liczbę punktów próbkowania wzdłuż ścieżki, dla których mają być zwracane dane wysokościowe. Parametr samples dzieli podaną wartość: path w uporządkowany zbiór równoodległych punktów na ścieżce.

Określanie lokalizacji

Prośby o pozycjonowanie są wskazywane za pomocą parametru locations, który wskazuje prośby o wysokość dla określonych lokalizacji przekazanych 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ą („|”) znak: 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 tekstowe z współrzędnymi geograficznymi są definiowane za pomocą cyfr w ciągu tekstowym rozdzielanym przecinkami. Przykład prawidłowej wartości locations: „40.714728,-73.998672”. Szerokość geograficzna wartości 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 – dowolną wartość 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 można przekazać do 512 współrzędnych linię łamaną, tworząc prawidłowy URL. Zwróć uwagę, że w przypadku przekazywania wielu współrzędnych, dokładność zwróconych danych może mieć niższą rozdzielczość niż w przypadku żądania danych dla jednej współrzędnej. Jeśli w parametrach „locations” lub „path” przekroczysz liczbę 512 punktów lub współrzędnych, zwrócona zostanie odpowiedź INVALID_REQUEST.

Określanie ścieżek

Próbkowane żądania ścieżek są wskazywane za pomocą parametru path i samples, które wskazują żądanie danych o wysokości wzdłuż ścieżki w określonych odstępach czasu. Podobnie jak w przypadku żądań dotyczących pozycji, które używają parametru locations, parametr path określa zestaw wartości szerokości i długości geograficznej. Inaczej niż w przypadku prośby o pozycję 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 na długości ścieżki na podstawie określonej liczby samples (w tym punktów końcowych).

Parametr path może przyjmować jedną z tych wartości: argumenty:

• Tablica zawierająca co najmniej 2 ciągi tekstowe z współrzędnymi rozdzielone przecinkami i oddzielone za pomocą znaku pionowej kreski (|): path=40.714728,-73.998672|-34.397,150.644
• Zakodowane współrzędne za pomocą funkcji Zakodowane Algorytm linii łamanej: path=enc:gfo}EtohhUxD@bAxJmGF

Ciągi współrzędnych szerokości i długości geograficznej są definiowane za pomocą liczb w ciągu tekstowym rozdzielanym przecinkami. Przykład: „40.714728,-73.998672|-34.397, 150.644” jest prawidłową wartością 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 zakresu od -90 do 90, a długość geograficzna – dowolną wartość z zakresu od -180 do 180. Jeśli określisz nieprawidłowa wartość szerokości lub długości geograficznej, żądanie zostanie odrzucone. jako złe żądanie.

W tablicy lub zakodowanej polilinii możesz podać maksymalnie 512 koordynat, zachowując prawidłowy adres URL. W przypadku przekazywania współrzędne, dokładność zwróconych danych może być mniejsza niż podczas żądania danych dla jednej współrzędnej. Przekroczenie liczby 512 punktów lub współrzędnych w polu „Lokalizacje” lub „ścieżka” zwraca odpowiedź INVALID_REQUEST.

Odpowiedzi dotyczące wysokości

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

Gdy kod stanu jest inny niż OK, mogą występować dodatkowe error_message w obiekcie odpowiedzi dotyczącej wysokości. To pole zawiera więcej szczegółowe informacje o przyczynach związanych z określonym kodem stanu.

Odpowiedź zawiera tablicę results z tymi elementami:

Obiekt location zawiera te elementy:

Przykłady wzniesienia pozycyjnego

W tym przykładzie żądamy wysokości w Denver w Kolorado, czyli w „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, Kolorado i Dolina Śmierci, Kalifornia).

To żądanie demonstruje użycie flagi output w pliku 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 XML output:

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 tych przykładach żądamy danych dotyczących wysokości w linii prostejpath od Mt. Whitney w Kalifornii do Badwater w Kalifornii, czyli najwyższego i najniższego punktu na kontynencie Stanów Zjednoczonych. Prosimy o 3 samples, więc obejmie on 2 punkty końcowe oraz parametr do połowy.

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>