Yükseltme istekleri
Elevation API istekleri, bir URL dizesi olarak oluşturulur. API, dünyadaki konumların yükseklik verilerini döndürür. Konum verilerini iki yöntemden birini kullanarak belirtirsiniz:
- Bir veya daha fazla
locations
kümesi olarak. path
boyunca bir dizi bağlantı noktası olarak.
Bu yaklaşımların her ikisi de konumları veya yol köşelerini tanımlamak için enlem/boylam koordinatlarını kullanır. Bu belgede, Elevation API URL'lerinin gerekli biçimi ve kullanılabilir parametreler açıklanmaktadır.
Elevation API, tek noktalı sorgular için mümkün olan en yüksek doğrulukla veri döndürür. Birden fazla konumu içeren toplu sorgular, verilerin düzelmesi nedeniyle, özellikle konumlar birbirinden ayrıldığında daha az doğrulukta veri döndürebilir.
Elevation API isteği aşağıdaki biçimdedir:
https://maps.googleapis.com/maps/api/elevation/outputFormat?parameters
Bu örnekte outputFormat
, aşağıdaki değerlerden biri olabilir:
json
(önerilir), JavaScript Object Notation (JSON) içindeki çıkışı belirtir veyaxml
,<ElevationResponse>
düğümü içinde sarmalanmış XML çıkışını gösterir.
Not: URL'lerin geçerli olmaları için doğru şekilde kodlanması gerekir ve tüm web hizmetleri için 16384 karakterle sınırlıdır. URL'lerinizi oluştururken bu sınıra dikkat edin. Farklı tarayıcıların, proxy'lerin ve sunucuların da farklı URL karakter sınırları olabileceğini unutmayın.
API anahtarı kullanan istekler için HTTPS gereklidir.
İstek parametreleri
Elevation API'ye gönderilen istekler, isteğin ayrı konumlar mı yoksa sıralı bir yol için mi olduğuna bağlı olarak farklı parametreler kullanır. Ayrık konumlar için, yükselti istekleri, istekte geçirilen belirli konumlardaki verileri döndürür; yollar için yükseklik istekleri bunun yerine belirtilen yol boyunca örneklenir.
Tüm URL'lerde standart olduğu gibi parametreler, "ve" (&
) karakteri kullanılarak ayrılır. Parametre 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. Nasıl anahtar alacağınızı öğrenin.
Konumsal istekler
locations
(zorunlu), dünya üzerinde yükseklik verilerinin döndürüleceği konumları tanımlar. Bu parametre, tek bir konumu virgülle ayrılmış {latitude,longitude} çifti (ör. "40.714728,-73.998672") veya dizi veya kodlanmış çoklu çizgi olarak iletilen birden fazla enlem/boylam çifti olarak alır. Bu parametre için 512 puan sınırı vardır. Daha fazla bilgi için aşağıdaki Konumları Belirtme konusuna bakın.
Örneklenmiş yol istekleri
path
(zorunlu), dünya üzerinde yükseklik verilerinin döndürüleceği yolu tanımlar. Bu parametre, dünyanın yüzeyi boyunca bir yol tanımlayan iki veya daha fazla sıralı {latitude,longitude} çiftinden oluşan bir kümeyi 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 Yolları Belirtme bölümüne bakın.samples
(zorunlu), bir yol boyunca yükseklik verilerinin döndürüleceği örnek noktalarının sayısını belirtir.samples
parametresi, belirtilenpath
öğesini yol boyunca sıralı bir eş mesafeli noktalar kümesine böler.
Yer belirtme
Konumsal istekler, belirli konumlar için enlem/boylam değerleri olarak iletilen yükseklik isteklerini belirten locations
parametresi kullanılarak belirtilir.
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ış koordinat dizisi:locations=40.714728,-73.998672|-34.397,150.644
- Kodlanmış Çoklu Çizgi Algoritması'nı kullanan kodlanmış koordinat grubu:
locations=enc:gfo}EtohhU
Enlem ve boylam koordinat dizeleri, virgülle ayrılmış bir metin dizesindeki sayılar 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 herhangi bir değeri, boylam değerleri ise -180
ile 180
arasında herhangi bir değeri alabilir. Geçersiz bir enlem veya boylam değeri belirtirseniz isteğiniz hatalı bir istek olarak reddedilir.
Geçerli bir URL oluşturmaya devam ederken, bir dizi veya kodlanmış çoklu çizgi içinde 512 koordinat iletebilirsiniz.
Birden fazla koordinat aktarılırken döndürülen verilerin doğruluğunun, tek bir koordinat için veri istenirken olduğundan daha düşük olabileceğini unutmayın.
"locations" veya "path" parametrelerinde 512 nokta veya koordinat aşıldığında INVALID_REQUEST
yanıtı döndürülür.
Yolları belirtme
Örneklenmiş yol istekleri, path
ve samples
parametreleri kullanılarak belirtilir. Bu da, belirtilen aralıklarda bir yol boyunca yükseklik verileri için istekte bulunulduğunu gösterir. locations
parametresini kullanan konumlandırma isteklerinde olduğu gibi, path
parametresi bir dizi enlem ve boylam değerini belirtir. Bununla birlikte path
, konumsal istekten farklı olarak sıralı bir köşe grubu belirtir. Yükseklik verilerini yalnızca köşe noktalarında döndürmek yerine, yol istekleri, belirtilen samples
sayısına (uç noktalar dahil) bağlı olarak yol boyunca örneklenir.
path
parametresi, aşağıdaki bağımsız değişkenlerden birini alabilir:
- Dikey çizgi ("
|
") karakteri kullanılarak ayrılmış iki veya daha fazla koordinat metin dizesinden oluşan bir dizi:path=40.714728,-73.998672|-34.397,150.644
- Kodlanmış Çoklu Çizgi Algoritması kullanılarak kodlanmış koordinatlar:
path=enc:gfo}EtohhUxD@bAxJmGF
Enlem ve boylam koordinat dizeleri, virgülle ayrılmış bir metin dizesindeki sayılar 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 herhangi bir değeri, boylam değerleri ise -180
ile 180
arasında herhangi bir değeri alabilir. Geçersiz bir enlem veya boylam değeri belirtirseniz isteğiniz hatalı bir istek olarak reddedilir.
Geçerli bir URL oluşturmaya devam ederken, bir dizi veya kodlanmış çoklu çizgi içinde 512 koordinat iletebilirsiniz. Birden fazla koordinat aktarılırken döndürülen verilerin doğruluğunun, tek bir koordinat için veri istenirken kullanılandan daha düşük olabileceğini unutmayın. "locations" veya "path" parametrelerinde 512 nokta veya koordinat aşıldığında INVALID_REQUEST
yanıtı döndürülür.
Yükseltme yanıtları
Yükseklik hizmeti, her geçerli istek için istek URL'sinde belirtilen biçimde bir Yükseklik 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ışında olduğunda, Yükseklik yanıt nesnesinde ek bir error_message
alanı olabilir. Bu alanda, belirtilen durum kodunun nedenleri hakkında daha ayrıntılı bilgiler yer alır.
Yanıt, aşağıdaki öğelere sahip 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 öğelere sahiptir:
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, Denver, Colorado'daki "Mile High City" adlı yerin JSON biçiminde yükseltilmesi istenmiştir:
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 çok yanıt gösterilmektedir (Denver, CO ve Death Valley, CA için).
Bu istek, JSON output
işaretinin kullanımını gösterir:
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 kullanımı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, Whitney, CA Dağı'ndan path
kıtasında Amerika Birleşik Devletleri'ndeki en yüksek ve en düşük noktalar olan Badwater'a kadar düz bir çizgi üzerinde yükseklik verileri talep edilmektedir. İki uç noktayı ve yarım noktayı içerecek şekilde üç samples
istiyoruz.
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>