Prośby o zmianę wysokości i odpowiedzi

Prośby o podniesienie

Żądania do interfejsu Elevation API są tworzone jako ciąg znaków adresu URL. Interfejs API zwraca dane dotyczące wysokości nad poziomem morza w przypadku 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 path.

Oba te podejścia używają współrzędnych szerokości i długości geograficznej do identyfikowania lokalizacji lub wierzchołków ścieżki. Ten dokument opisuje wymagany format adresów URL interfejsu Elevation API i dostępne parametry.

Interfejs Elevation API zwraca dane dla zapytań dotyczących pojedynczego punktu z największą możliwą dokładnością. Zapytania zbiorcze obejmujące wiele lokalizacji mogą zwracać dane o mniejszej dokładności, zwłaszcza jeśli lokalizacje są od siebie oddalone, ponieważ dane są w pewnym stopniu wygładzane.

Żądanie do 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) – oznacza dane wyjściowe w formacie JSON (JavaScript Object Notation);
• xml, wskazuje dane wyjściowe w formacie XML ujęte w element <ElevationResponse>.

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ń, które używają klucza interfejsu API, wymagany jest protokół HTTPS.

Parametry żądania

Żądania wysyłane do interfejsu Elevation API korzystają z różnych parametrów w zależności od tego, czy żądanie dotyczy pojedynczych lokalizacji, czy uporządkowanej ścieżki. 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 Twoją aplikację na potrzeby zarządzania limitem. Dowiedz się, jak uzyskać klucz.

Żądania dotyczące pozycji

• locations (wymagany) określa lokalizację lub lokalizacje na Ziemi, z których mają być zwracane dane o wysokości. Ten parametr może przyjmować jedną lokalizację jako parę {szerokość geograficzna,długość geograficzna} rozdzieloną przecinkami (np. „40.714728,-73.998672”) lub wiele par szerokości i długości geograficznej przekazanych 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.

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. Ten parametr ma limit 512 punktów. Więcej informacji znajdziesz w sekcji 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 daną ścieżkę pathna uporządkowany zbiór punktów równoodległych wzdłuż ścieżki.

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:

• Pojedyncza współrzędna: locations=40.714728,-73.998672
• Tablica współrzędnych rozdzielona za pomocą znaku pionowej kreski (|): locations=40.714728,-73.998672|-34.397,150.644
• Zbiór zakodowanych współrzędnych za pomocą algorytmu zakodowanej linii łamanej:locations=enc:gfo}EtohhU

Ciągi tekstowe współrzędnych geograficznych są definiowane za pomocą cyfr w ciągu tekstowym rozdzielanym przecinkami. Przykład prawidłowej wartości locations: „40.714728,-73.998672”. 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 podasz nieprawidłową wartość szerokości lub długości geograficznej, Twoje żądanie zostanie odrzucone jako nieprawidłowe.

W tablicy lub zakodowanej polilinii możesz podać maksymalnie 512 koordynat, zachowując prawidłowy adres URL. Pamiętaj, że gdy podasz wiele współrzędnych, dokładność zwróconych danych może być mniejsza niż w przypadku żądania danych dla pojedynczej 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

Żądania dotyczące ścieżki próbkowanej są wskazywane za pomocą parametrów path i samples, które wskazują żądanie danych wysokościowych wzdłuż ścieżki w określonych odstępach czasowych. Podobnie jak w przypadku żądań pozycyjnych używających parametru locations, parametr path określa zestaw wartości szerokości i długości geograficznej. W odróżnieniu od żądania dotyczącego pozycji 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 na 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 z współrzędnymi rozdzielone przecinkami i oddzielone za pomocą znaku pionowej kreski (|): path=40.714728,-73.998672|-34.397,150.644
• Kodowane współrzędne za pomocą kodowanego algorytmu linii łamanej: path=enc:gfo}EtohhUxD@bAxJmGF

Ciągi tekstowe współrzędnych geograficznych są definiowane za pomocą cyfr w ciągu tekstowym rozdzielanym 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 kuli ziemskiej. 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 polilinii możesz podać maksymalnie 512 koordynat, zachowując prawidłowy adres URL. Pamiętaj, że gdy podasz wiele współrzędnych, dokładność zwróconych danych może być mniejsza niż w przypadku żądania danych dla pojedynczej współrzędnej. Jeśli w parametrach „locations” lub „path” podasz więcej niż 512 punktów lub współrzędnych, zwrócona zostanie odpowiedź INVALID_REQUEST.

Odpowiedzi dotyczące wzniesienia

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

Jeśli kod stanu jest inny niż OK, w obiekcie odpowiedzi Elevation może być dodatkowe pole error_message. To pole zawiera więcej szczegółowych informacji o przyczynach danego kodu 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 pokazuje wiele odpowiedzi (dla Denver w Kolorado i Death Valley w Kalifornii).

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

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>

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, aby uwzględnić 2 punkty końcowe i punkt pośredni.

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>