Yükseklik istekleri
Elevation API istekleri bir URL dizesi olarak oluşturulur. API, dünyadaki konumların rakım verilerini döndürür. Konum verilerini iki yöntemden biriyle belirtirsiniz:
- Bir veya daha fazla
locations
grubu olarak. path
boyunca birbirine bağlı noktalardan oluşan bir seri olarak.
Bu yaklaşımlardan herhangi biri, konumları veya yol köşe noktalarını tanımlamak için enlem/boylam koordinatlarını kullanır. Bu dokümanda, Elevation API URL'lerinin gerekli biçimi ve kullanılabilen parametreler açıklanmaktadır.
Elevation API, tek nokta sorguları için mümkün olan en yüksek doğrulukta veriler döndürür. Birden fazla konum içeren toplu sorgular, verilerin yumuşatılması nedeniyle özellikle konumlar birbirinden uzaksa daha az doğrulukla veri döndürebilir.
Elevation API isteği aşağıdaki biçimdedir:
https://maps.googleapis.com/maps/api/elevation/outputFormat?parameters
Burada outputFormat
aşağıdaki değerlerden biri olabilir:
json
(önerilen), JavaScript Nesne Gösterimi (JSON) biçiminde çıkışı gösterir veyaxml
, XML'deki çıkışı,<ElevationResponse>
düğümüne sarmalanmış şekilde gösterir.
Not: URL'lerin geçerli olması için doğru şekilde kodlanması gerekir ve tüm web hizmetleri için 16.384 karakterle sınırlıdır. URL'lerinizi oluştururken bu sınırı göz önünde bulundurun. Farklı tarayıcıların, proxy'lerin ve sunucuların farklı URL karakter sınırlamaları olabileceğini unutmayın.
API anahtarı kullanan istekler için HTTPS gereklidir.
İstek parametreleri
Elevation API'ye yapılan istekler, isteğin ayrı konumlar için mi yoksa sıralı bir yol için mi olduğuna bağlı olarak farklı parametreler kullanır. Ayrık konumlar için yükseklik istekleri, istekte iletilen belirli konumlarla ilgili verileri döndürür. Yollar için ise yükseklik istekleri, belirli yol boyunca örneklenir.
Tüm URL'lerde olduğu gibi, parametreler "ve" işareti (&
) karakteri kullanılarak ayrılır. Parametrelerin listesi ve olası değerleri aşağıda belirtilmiştir.
Tüm istekler
key
: (zorunlu) Uygulamanızın API anahtarı. Bu anahtar, kota yönetimi amacıyla uygulamanızı tanımlar. Anahtar edinme hakkında bilgi edinin.
Konumsal istekler
locations
(zorunlu), dünyadaki hangi konumlardan yükseklik verilerinin döndürüleceğini tanımlar. Bu parametre, virgülle ayrılmış {latitude,longitude} çifti olarak tek bir konumu (ör. "40.714728,-73.998672") veya dizi ya da kodlanmış poli çizgisi olarak iletilen birden fazla enlem/boylam çiftini alır. Bu parametre için 512 nokta sınırı vardır. Daha fazla bilgi için aşağıdaki Konum belirtme bölümüne bakın.
Örneklenmiş yol istekleri
path
(zorunlu), yeryüzünde yükseklik verilerinin döndürüleceği bir yol tanımlar. Bu parametre, dünyanın yüzeyinde bir yol tanımlayan iki veya daha fazla sıralı {latitude,longitude} çifti kümesi tanımlar. Bu parametre, aşağıda açıklanansamples
parametresiyle birlikte kullanılmalıdır. Bu parametre için 512 puan sınırı vardır. Daha fazla bilgi için aşağıdaki Yol Belirtme bölümüne bakın.samples
(zorunlu), bir yol boyunca yükseklik verilerinin döndürüleceği örnek nokta sayısını belirtir.samples
parametresi, verilenpath
değerini yola eşit uzaklıktaki düzenli bir nokta kümesine böler.
Konumları belirtme
Konum istekleri, locations
parametresi kullanılarak belirtilir. Bu parametre, enlem/boylam değerleri olarak iletilen belirli konumlar için yükseklik isteklerini belirtir.
locations
parametresi aşağıdaki bağımsız değişkenleri alabilir:
- Tek bir koordinat:
locations=40.714728,-73.998672
- Dikey çizgi ("
|
") karakteri kullanılarak ayrılmış bir koordinat dizisi:locations=40.714728,-73.998672|-34.397,150.644
- Kodlanmış Poli çizgi Algoritması'nı kullanan kodlanmış koordinatlar grubu:
locations=enc:gfo}EtohhU
Enlem ve boylam koordinatı dizeleri, virgül ile ayrılmış bir metin dizesi içinde rakamlar kullanılarak tanımlanır. Örneğin, "40.714728,-73.998672" geçerli bir locations
değeridir. Enlem ve boylam değerleri, dünya üzerinde geçerli bir konuma karşılık gelmelidir. Enlemler -90
ile 90
arasında, boylamlar ise -180
ile 180
arasında herhangi bir değer alabilir. Geçersiz bir enlem veya boylam değeri belirtirseniz isteğiniz hatalı istek olarak reddedilir.
Geçerli bir URL oluştururken bir dizi veya kodlanmış çoklu çizgi içinde 512'ye kadar koordinat iletebilirsiniz.
Birden fazla koordinat iletirken döndürülen verilerin doğruluğunun, tek bir koordinat için veri istendiğinden daha düşük çözünürlükte olabileceğini unutmayın.
"konumlar" veya "yol" parametrelerinde 512 nokta veya koordinatın aşılması INVALID_REQUEST
yanıtı döndürür.
Yolları belirtme
Örneklenen yol istekleri, path
ve samples
parametreleri kullanılarak belirtilir. Bu parametreler, belirtilen aralıklarla bir yol boyunca yükseklik verisi isteğinde bulunulduğunu gösterir. locations
parametresini kullanan konumsal isteklerde olduğu gibi, path
parametresi de bir dizi enlem ve boylam değerini belirtir. Ancak path
, konumsal isteklerin aksine sıralı bir köşe noktası kümesi belirtir. Yol istekleri, yalnızca köşe noktalarında yükseklik verileri döndürmek yerine, belirtilen samples
sayısına (uç noktalar dahil) göre yolun uzunluğu boyunca örneklenir.
path
parametresi aşağıdaki bağımsız değişkenlerden birini alabilir:
- Dikey çizgi ("
|
") karakteri kullanılarak ayrılmış, virgülle ayrılmış iki veya daha fazla koordinat metin dizesi dizisi:path=40.714728,-73.998672|-34.397,150.644
- Kodlanmış Poli çizgi Algoritması kullanılarak kodlanmış koordinatlar:
path=enc:gfo}EtohhUxD@bAxJmGF
Enlem ve boylam koordinatı dizeleri, virgül ile ayrılmış bir metin dizesi içinde rakamlar kullanılarak tanımlanır. Örneğin, "40.714728,-73.998672|-34.397, 150.644" geçerli bir path
değeridir. Enlem ve boylam değerleri, dünya üzerinde geçerli bir konuma karşılık gelmelidir. Enlemler -90
ile 90
arasında, boylamlar ise -180
ile 180
arasında herhangi bir değer alabilir. Geçersiz bir enlem veya boylam değeri belirtirseniz isteğiniz hatalı istek olarak reddedilir.
Geçerli bir URL oluştururken bir dizi veya kodlanmış çoklu çizgi içinde 512'ye kadar koordinat iletebilirsiniz. Birden fazla koordinat iletirken döndürülen verilerin doğruluğunun, tek bir koordinat için veri istendiğinden daha düşük çözünürlükte olabileceğini unutmayın. "konumlar" veya "yol" parametrelerinde 512 nokta veya koordinatı aşmak INVALID_REQUEST
yanıtı döndürür.
Rakım yanıtları
Elevation hizmeti, her geçerli istek için istek URL'sinde belirtilen biçimde bir Elevation yanıtı döndürür.
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.
Durum kodu OK
dışındaysa Yükseklik yanıt nesnesinde ek bir error_message
alanı olabilir. Bu alan, belirtilen durum kodunun nedenleri hakkında daha ayrıntılı bilgi içerir.
Yanıt, aşağıdaki öğeleri içeren bir results
dizisi içerir:
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. |
location
nesnesi aşağıdaki öğeleri içerir:
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 |
Konumsal yükseklik örnekleri
Aşağıdaki örnekte, "Mile High City" (1.600 metre yükseklikteki şehir) olarak bilinen Colorado, Denver için JSON biçiminde yükseklik bilgisi istenir:
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>
Aşağıdaki örnekte birden fazla yanıt gösterilmektedir (Denver, CO ve Death Valley, CA için).
Bu istek, JSON output
işaretinin kullanılmasını göstermektedir:
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'
Bu istek, XML output
işaretinin nasıl kullanıldığını gösterir:
https://maps.googleapis.com/maps/api/elevation/xml?locations=39.7391536,-104.9847034|36.455556,-116.866667&key=YOUR_API_KEY
Örnek JSON ve XML yanıtlarını görmek için aşağıdaki sekmeleri seçin.
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>
Aşağıdaki örneklerde, Kaliforniya'daki Whitney Dağı'ndan Kaliforniya'daki Badwater'e (ABD anakarasındaki en yüksek ve en düşük noktalar) path
düz bir çizgi boyunca yükseklik verileri istenir. Üç samples
isteğinde bulunuruz. Bu sayede iki uç nokta ve orta noktayı da dahil edebiliriz.
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>