Prośby o zmianę wysokości i odpowiedzi

Prośby o podniesienie wysokości

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

  • Jako zbiór zawierający co najmniej 1 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ż występuje wtedy pewne wygładzanie danych.

Żą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), wskazuje dane wyjściowe w formacie JavaScript Object Notation (JSON); lub
  • 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 również mogą mieć różne limity znaków adresu 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 konkretnych 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.

Standardowo we wszystkich adresach URL parametry są oddzielane znakiem „&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 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 może przyjmować pojedynczą 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. Ten konkretny parametr ma limit 512 punktów. Więcej informacji znajdziesz w sekcji Określanie lokalizacji poniżej.

Próbkowe żądania ścieżki

  • path (wymagany) określa ścieżkę na Ziemi, dla której zwracają dane o wysokości. Ten parametr określa zestaw co najmniej dwóch uporządkowanych par {width,longitude}, które określają ścieżkę wzdłuż powierzchni Ziemi. Tego parametru należy używać 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óbnych na ścieżce, dla których mają być zwracane dane o wysokości. Parametr samples dzieli daną ścieżkę pathna uporządkowany zbiór punktów równoodległych wzdłuż ścieżki.

Określanie lokalizacji

Żądania pozycji są wskazywane za pomocą parametru locations, który wskazuje żądania wysokości względnej dla określonych lokalizacji przekazywane 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 rozdzielona za pomocą znaku pionowej kreski (|): locations=40.714728,-73.998672|-34.397,150.644
  • Zestaw zakodowanych współrzędnych za pomocą zakodowanego algorytmu 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” to prawidłowa wartość 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 – dowolną wartość z zakresu od -180 do 180. Jeśli podasz nieprawidłową wartość szerokości lub długości geograficznej, żądanie zostanie odrzucone jako błędne.

W tablicy lub zakodowanej linii łamanej można przekazać do 512 współrzędnych, nadal tworząc 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 jednej współrzędnej. Przekroczenie 512 punktów lub współrzędnych w parametrach „locations” lub „path” powoduje zwrócenie odpowiedzi INVALID_REQUEST.

Określanie ścieżek

Próbkowane żądania ścieżek są wskazywane za pomocą parametrów path i samples, które wskazują żądanie danych o wzroście wysokości na ścieżce w określonych odstępach czasu. Podobnie jak w przypadku żądań pozycyjnych z parametrem 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 z co najmniej 2 ciągami tekstowymi współrzędnych rozdzielonych przecinkami, które są rozdzielone pionową kreską („|”): path=40.714728,-73.998672|-34.397,150.644
  • Współrzędne zakodowane za pomocą kodowanego algorytmu 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 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, żądanie zostanie odrzucone jako błędne.

Możesz przekazać maksymalnie 512 współrzędnych w tablicy lub zakodowanej polilinii, zachowując przy tym 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. Przekroczenie 512 punktów lub współrzędnych w parametrze „locations” (lokalizacja) lub „path” (ścieżka) zwraca odpowiedź INVALID_REQUEST.

Odpowiedzi dotyczące wzniesienia

W przypadku każdego prawidłowego żądania usługa wysokości względnej zwróci odpowiedź dotyczącą wysokości w formacie wskazanym w adresie URL żądania.

ElevationResponse

FieldRequiredTypeDescription
required Array<ElevationResult> See ElevationResult for more information.
requiredElevationStatus See ElevationStatus for more information.
optionalstring

When the service returns a status code other than OK, there may be an additional error_message field within the response object. This field contains more detailed information about thereasons behind the given status code. This field is not always returned, and its content is subject to change.

ElevationStatus

Status codes returned by service.

  • OK indicating the API request was successful.
  • DATA_NOT_AVAILABLE indicating that there's no available data for the input locations.
  • INVALID_REQUEST indicating the API request was malformed.
  • OVER_DAILY_LIMIT indicating any of the following:
    • The API key is missing or invalid.
    • Billing has not been enabled on your account.
    • A self-imposed usage cap has been exceeded.
    • The provided method of payment is no longer valid (for example, a credit card has expired).
  • OVER_QUERY_LIMIT indicating the requestor has exceeded quota.
  • REQUEST_DENIED indicating the API did not complete the request.
  • UNKNOWN_ERROR indicating an unknown error.

Gdy kod stanu jest inny niż OK, w obiekcie odpowiedzi dotyczącej wysokości może znajdować się dodatkowe pole error_message. To pole zawiera bardziej szczegółowe informacje o przyczynach występowania danego kodu stanu.

Odpowiedź zawiera tablicę results z tymi elementami:

ElevationResult

FieldRequiredTypeDescription
requirednumber

The elevation of the location in meters.

requiredLatLngLiteral

A location element of the position for which elevation data is being computed. Note that for path requests, the set of location elements will contain the sampled points along the path.

See LatLngLiteral for more information.

optionalnumber

The value indicating the maximum distance between data points from which the elevation was interpolated, in meters. This property will be missing if the resolution is not known. Note that elevation data becomes more coarse (larger resolution values) when multiple points are passed. To obtain the most accurate elevation value for a point, it should be queried independently.

Obiekt location zawiera te elementy:

LatLngLiteral

An object describing a specific location with Latitude and Longitude in decimal degrees.

FieldRequiredTypeDescription
requirednumber

Latitude in decimal degrees

requirednumber

Longitude in decimal degrees

Przykłady pozycjonowania wysokości

Poniższy przykład wymaga podania wysokości dla Denver (Kolorado) i „Mile High City” w formacie JSON:

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 wiele odpowiedzi (dla Denver w Kolorado i Death Valley w Kalifornii).

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

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 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. Potrzebujemy 3 elementów samples, aby uwzględnić 2 punkty końcowe i połowę drogi.

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>