Yükseklik istekleri ve yanıtları

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 kümesi olarak.
  • path boyunca birbirine bağlı noktalardan oluşan bir seri 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 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

Bu örnekte outputFormat, aşağıdaki değerlerden biri olabilir:

  • json (önerilir), JavaScript Nesne Gösterimi (JSON) biçiminde çıkışı gösterir veya
  • xml, <ElevationResponse> düğümü içinde sarmalanmış XML çıkışını 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ı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 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 standart olduğu gibi parametreler, "ve" (&amp;) 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. Anahtar edinme hakkında bilgi edinin.

Konumsal istekler

  • locations (zorunlu), dünya üzerinde yükseklik verilerinin döndürüleceği konumları 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ış bir poli çizgisi olarak iletilen birden fazla enlem/boylam çiftini alır. Bu parametre için 512 puan 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), 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 Yol Belirleme 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, verilen path değerini yola eşit uzaklıktaki düzenli bir nokta kümesine böler.

Konumları 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 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. "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ıklarla 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. Ancak path, konumsal isteklerin aksine sıralı bir köşe noktası kümesi 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ış, 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ü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ş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ı

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

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.

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

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.

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

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

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 ç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 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, pathWhitney, CA Dağı'ndan ve Kıtasal ABD'deki en yüksek ve en düşük noktalar olan Badwater, CA'ya uzanan, düz bir çizgi boyunca 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>