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. Ty określasz dane o lokalizacji na jeden z dwóch sposobów:

  • Jako zbiór zawierający co najmniej 1 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 określenia 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 jednocześnie, ponieważ dane są w pewien sposób wygładzane.

Żądanie do interfejsu Elevation API ma taką postać:

https://maps.googleapis.com/maps/api/elevation/outputFormat?parameters

gdzie outputFormat może być jedną z tych wartości:

  • json (zalecany), wskazuje dane wyjściowe w JavaScript Object Notation (JSON); lub
  • xml, wskazuje dane wyjściowe w formacie XML, opakowane w <ElevationResponse> węzeł.

Uwaga: adresy URL muszą zawierać prawidłowo zakodowane , a jego długość dla wszystkich usług internetowych jest ograniczona do 16 384 znaków. Pamiętaj o tym podczas tworzenia adresów URL. Pamiętaj, że różne przeglądarki, serwerów proxy i serwery mogą mieć także różne limity znaków adresu 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 prośba dotyczy konkretnych lokalizacji, uporządkowaną ścieżkę. W przypadku dyskretnych lokalizacji żądanie zwrotu wzniesień dane na temat konkretnych lokalizacji przekazanych w prośbie; ścieżek, Żądania podniesienia uprawnień są próbkowane wzdłuż podanej ścieżki.

Zgodnie ze standardem we wszystkich adresach URL parametry są rozdzielone przy użyciu znaku ampersand (&amp;). Lista parametrów a ich możliwe wartości podano poniżej.

Wszystkie prośby

  • key – (wymagany) Twój wniosek klucz interfejsu API. Ten klucz identyfikuje aplikację na potrzeby zarządzania limitami. Dowiedz się, jak uzyskać klucz.

Żądania pozycjonowania

  • locations (wymagany) określa lokalizacje na Ziemia, z której mają zostać zwrócone dane o wysokości. Ten parametr przyjmuje albo pojedyncza lokalizacja w postaci rozdzielonej przecinkami pary {szerokość,długość} (np. „40.714728,-73.998672”) lub wiele par szerokości i długości geograficznej przekazywane 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óbkowane żądania ścieżek

  • path (wymagany) określa ścieżkę na Ziemi dla które mają zwrócić dane o wysokości. Ten parametr określa zestaw dwóch lub bardziej uporządkowane pary {szerokość, długość}, które definiują ścieżkę wzdłuż powierzchni za kulisy. Tego parametru należy używać w połączeniu z parametrem samples opisane 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 (wymagany) określa liczbę próbek. punktów na ścieżce, dla których mają być zwracane dane o wysokości n.p.m. Parametr samples dzieli podaną wartość: path w uporządkowany zbiór równoodległych punktów na ścieżce.

Określanie lokalizacji

Żądania pozycjonowania są zgłaszane za pomocą funkcji Parametr locations wskazujący żądania podniesienia uprawnień dla konkretnych lokalizacji przekazanych jako szerokości i długości geograficznej.

Parametr locations może przyjmować takie wartości 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
  • Zestaw zakodowanych współrzędnych przy użyciu funkcji Zakodowane Algorytm linii łamanej: locations=enc:gfo}EtohhU

Ciągi współrzędnych szerokości i długości geograficznej są definiowane za pomocą liczb w ciągu tekstowym rozdzielanym przecinkami. Na przykład „40.714728,-73.998672” to prawidłowa wartość locations. Szerokość geograficzna oraz wartości długości geograficznej muszą odpowiadać prawidłowej lokalizacji na powierzchni Ziemi. Szerokość geograficzna może mieć dowolną wartość z zakresu -90 i 90, podczas gdy długość geograficzna może wynosić dowolna 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 można przekazać do 512 współrzędnych linię łamaną, tworząc prawidłowy adres 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. Przekroczenie liczby 512 punktów lub współrzędnych w sekcji „lokalizacja” lub „ścieżka” parametr zwraca INVALID_REQUEST odpowiedź.

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ń pozycjonowania korzystających z locations, parametr path określa zbiór 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 zwrotu dane o wzroście wysokości tylko w wierzchołkach, żądania ścieżki są próbkowane wzdłuż długość ścieżki na podstawie liczby zdarzeń typu samples. (łącznie z punktami końcowymi).

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

  • Tablica z co najmniej 2 ciągami tekstowymi współrzędnych rozdzielonych przecinkami oddzielone pionową kreską („|”) znak: 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. Długość i szerokość geograficzna muszą odpowiadać w odpowiednim miejscu na kuli ziemskiej. Szerokość geograficzna może mieć dowolną wartość z zakresu -90 i 90, podczas gdy długość geograficzna może wynosić dowolna 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 można przekazać do 512 współrzędnych linię łamaną, tworzą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. Przekraczanie 512 punktów lub współrzędnych w polu „Lokalizacje” lub „ścieżka” zwraca odpowiedź INVALID_REQUEST.

Odpowiedzi dotyczące wysokości

Dla każdego prawidłowego żądania usługa wysokości względnej zwróci informację o 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, 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:

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

W poniższym przykładzie żądamy wysokości n.p.m. w Denver: Kolorado, „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 przedstawia wiele odpowiedzi (dla Denver, Kolorado i Dolina Śmierci, Kalifornia).

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

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.

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 zażądano danych wysokości n.p.m. wzdłuż linii prostej path od góry Whitney w Kalifornii do Badwater, Kalifornia, najwyższego najniższych punktów w kontynentalnej części Stanów Zjednoczonych. Prosimy o 3 samples, więc obejmie on 2 punkty końcowe oraz parametr do połowy.

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>