Yükseklik istekleri ve yanıtları

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 veya
• xml, <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çıklanan samples 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, belirtilen path öğ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.

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:

location nesnesi aşağıdaki öğelere sahiptir:

Konumsal yükseklik örnekleri

Aşağıdaki örnekte, Denver, Colorado'daki "Mile High City" adlı yerin JSON biçiminde yükseltilmesi istenmiştir:

https://maps.googleapis.com/maps/api/elevation/json
  ?locations=39.7391536%2C-104.9847034
  &key=YOUR_API_KEY

curl -L -X GET 'https://maps.googleapis.com/maps/api/elevation/json?locations=39.7391536%2C-104.9847034&key=YOUR_API_KEY'

{
  "results":
    [
      {
        "elevation": 1608.637939453125,
        "location": { "lat": 39.7391536, "lng": -104.9847034 },
        "resolution": 4.771975994110107,
      },
    ],
  "status": "OK",
}

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

https://maps.googleapis.com/maps/api/elevation/json
  ?locations=39.7391536%2C-104.9847034%7C36.455556%2C-116.866667
  &key=YOUR_API_KEY

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.

{
  "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",
}

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

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

{
  "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",
}

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