Prośby o zmianę wysokości i odpowiedzi

Prośby o podwyższenie

Żądania do interfejsu Elevation API mają postać ciągu adresu URL. Interfejs API zwraca dane o wysokości dla poszczególnych lokalizacji na Ziemi. Dane o lokalizacji określa się na jeden z dwóch sposobów:

  • Jako zestaw obejmujący co najmniej 1 element locations.
  • Jako seria połączonych punktów na linii path.

Każda z tych metod wykorzystuje współrzędne szerokości i długości geograficznej do identyfikowania lokalizacji lub wierzchołków ścieżek. W tym dokumencie opisujemy wymagany format adresów URL interfejsu Elevation API oraz dostępne parametry.

Elevation API zwraca dane dla zapytań jednopunktowych o największej dokładności. Zapytania zbiorcze dotyczące wielu lokalizacji mogą zwracać dane z mniejszą dokładnością, zwłaszcza gdy lokalizacje są rozproszone, ponieważ dane są wygładzone.

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

Uwaga: prawidłowe adresy URL muszą być prawidłowo zakodowane, a ich długość we wszystkich usługach internetowych jest ograniczona do 16 384 znaków. Pamiętaj o tym limicie podczas tworzenia adresów URL. Pamiętaj, że różne przeglądarki, serwery proxy i serwery mogą mieć inne limity znaków.

W przypadku żądań korzystających z klucza interfejsu API protokół HTTPS jest wymagany.

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 odrębnych lokalizacji są to żądania danych o wzroście wysokości, które dotyczą określonych lokalizacji przekazanych w żądaniu. W przypadku ścieżek żądania podwyższenia są próbkowane wzdłuż danej ścieżki.

Zgodnie ze standardem we wszystkich adresach URL parametry są rozdzielone znakami ampersand (&amp;). Poniżej znajdziesz listę parametrów i ich możliwe wartości.

Wszystkie prośby

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

Żądania pozycjonowania

  • locations (wymagany) określa lokalizacje na Ziemi, z których mają zostać zwrócone dane o wysokości. Ten parametr przyjmuje pojedynczą lokalizację jako parę {szerokość,długość geograficzna} rozdzielaną przecinkami (np. „40.714728,-73.998672”) lub wiele par szerokości i długości geograficznej przekazanych w postaci tablicy lub zakodowanej linii łamanej. Ten parametr ma limit 512 punktów. Więcej informacji znajdziesz w sekcji Określanie lokalizacji poniżej.

Próbkowana ścieżka żądań

  • path (wymagany) określa ścieżkę na Ziemi, dla której zostaną zwrócone dane o wysokości. Ten parametr określa zbiór co najmniej 2 uporządkowanych par {szerokość,długość geograficzna} wyznaczający ścieżkę wzdłuż powierzchni Ziemi. Tego parametru należy używać w połączeniu z parametrem samples opisanym poniżej. Ten konkretny parametr może mieć maksymalnie 512 punktów. Więcej informacji znajdziesz w sekcji Określanie ścieżek poniżej.
  • samples (wymagany) określa liczbę przykładowych punktów na ścieżce, dla których mają zostać zwrócone dane o wysokości. Parametr samples dzieli dane path na uporządkowany zestaw równoodległych punktów na ścieżce.

Określanie lokalizacji

Żądania informacji o pozycji są podawane za pomocą parametru locations, który wskazuje żądania dotyczące wysokości w przypadku konkretnych lokalizacji przekazywane 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 rozdzielonych pionową kreską („|”): locations=40.714728,-73.998672|-34.397,150.644
  • Zbiór współrzędnych zakodowanych za pomocą algorytmu zakodowanego łamanego: locations=enc:gfo}EtohhU

Ciągi współrzędnych szerokości i długości geograficznej są definiowane za pomocą cyfr zawartych w ciągu tekstowym rozdzielanym przecinkami. Na przykład „40.714728,-73.998672” to prawidłowa wartość locations. Długość i szerokość geograficzna muszą odpowiadać prawidłowej lokalizacji na powierzchni Ziemi. Szerokość geograficzna może mieć 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, żądanie zostanie odrzucone jako nieprawidłowe.

W obrębie tablicy lub zakodowanej linii łamanej możesz przekazać do 512 współrzędnych, tworząc prawidłowy adres URL. Pamiętaj, że podczas przekazywania wielu współrzędnych dokładność zwracanych danych może być mniejsza niż w przypadku żądań danych dla jednej współrzędnych. Przekroczenie 512 punktów lub współrzędnych w parametrach „locations” lub „path” zwraca odpowiedź INVALID_REQUEST.

Określanie ścieżek

Próbkowane żądania ścieżek są oznaczone za pomocą parametrów path i samples, co wskazuje na żądanie danych o wysokości wzdłuż ścieżki w określonych odstępach czasu. Tak jak w przypadku żądań pozycjonowania korzystających z parametru locations parametr path określa zestaw wartości szerokości i długości geograficznej. W przeciwieństwie do żądania pozycjonowania path określa jednak uporządkowany zestaw wierzchołków. Zamiast zwracać dane o wysokości tylko w wierzchołkach, żądania dotyczące ścieżek są próbkowane według długości ścieżki na podstawie określonej liczby samples (z uwzględnieniem punktów końcowych).

Parametr path może przyjmować jeden z tych argumentów:

  • Tablica składająca się z co najmniej 2 ciągów tekstowych rozdzielonych przecinkami rozdzielonych pionową kreską („|”): path=40.714728,-73.998672|-34.397,150.644
  • Współrzędne zakodowane za pomocą algorytmu zakodowanego łamanego: path=enc:gfo}EtohhUxD@bAxJmGF

Ciągi współrzędnych szerokości i długości geograficznej są definiowane za pomocą cyfr zawartych w ciągu tekstowym rozdzielanym przecinkami. Na przykład „40.714728,-73.998672|-34.397, 150.644” to prawidłowa wartość path. Długość i szerokość geograficzna muszą odpowiadać prawidłowej lokalizacji na powierzchni Ziemi. Szerokość geograficzna może mieć 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, żądanie zostanie odrzucone jako nieprawidłowe.

W obrębie tablicy lub zakodowanej linii łamanej możesz przekazać do 512 współrzędnych, tworząc prawidłowy adres URL. Pamiętaj, że podczas przekazywania wielu współrzędnych dokładność zwracanych danych może być mniejsza niż w przypadku żądania danych dla jednej współrzędnych. Przekroczenie 512 punktów lub współrzędnych w parametrach „locations” lub „path” zwraca odpowiedź 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

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.

Jeśli kod stanu jest inny niż OK, w obiekcie odpowiedzi podniesienia uprawnień może znajdować się dodatkowe pole error_message. To pole zawiera bardziej szczegółowe informacje o przyczynach pojawienia się 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 wysokości pozycjonalnej

Ten przykład wymaga podania wysokości w Denver w Kolorado czy „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 (w Denver, Kolorado i Dolinie Śmierci w Kalifornii).

To żądanie pokazuje, jak używać flagi JSON output:

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

Wybierz 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 prośba o dane o wysokości wzdłuż linii prostej path z góry Whitney w Kalifornii do Badwater (Kalifornia) – najwyższego i najniższego punktu kontynentalnego Stanów Zjednoczonych. Prosimy o 3 elementy samples, więc będzie to 2 punkty końcowe i połowa punktu pośredniego.

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>