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); lubxml
, 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 (&
). 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 parametremsamples
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. Parametrsamples
dzieli danepath
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
Field | Required | Type | Description |
---|---|---|---|
| required | Array<ElevationResult> | See ElevationResult for more information. |
| required | ElevationStatus | See ElevationStatus for more information. |
| optional | string |
When the service returns a status code other than |
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
Field | Required | Type | Description |
---|---|---|---|
| required | number | The elevation of the location in meters. |
| required | LatLngLiteral | 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. |
| optional | number | 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.
Field | Required | Type | Description |
---|---|---|---|
| required | number | Latitude in decimal degrees |
| required | number | 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>