Yükseklik istekleri ve yanıtları

Yükseklik 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 şekilde belirtebilirsiniz:

  • Bir veya daha fazla locations kümesi olarak.
  • path boyunca birbirine bağlı noktalar dizisi olarak.

Bu yaklaşımların her ikisinde de konumları veya yol köşelerini belirlemek için enlem/boylam koordinatları kullanılır. Bu belgede, Elevation API URL'lerinin gerekli biçimi ve kullanılabilir 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, özellikle konumlar birbirinden uzaksa verilerin düzeltilmesi nedeniyle daha az doğru veriler döndürebilir.

Elevation API isteği aşağıdaki biçimde olur:

https://maps.googleapis.com/maps/api/elevation/outputFormat?parameters

Burada outputFormat aşağıdaki değerlerden biri olabilir:

  • json (önerilir), çıktının JavaScript Object Notation (JSON) biçiminde olduğunu gösterir veya
  • xml, XML'deki çıktıyı gösterir ve <ElevationResponse> düğümü içinde sarmalanır.

Not: URL'lerin geçerli olması için düzgün ş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 URL karakter sınırlarının da farklı olabileceğini unutmayın.

API anahtarı kullanan istekler için HTTPS gereklidir.

İstek parametreleri

Elevation API'ye yapılan isteklerde, isteğin ayrı konumlar için mi yoksa sıralı bir yol için mi olduğuna bağlı olarak farklı parametreler kullanılır. Ayrı konumlar için yükseklik istekleri, istekte iletilen belirli konumlara ilişkin verileri döndürür. Yollar için ise yükseklik istekleri, verilen yol boyunca örneklenir.

Tüm URL'lerde standart olduğu gibi, parametreler "ve" işareti (&amp;) 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. Nasıl anahtar alacağınızı öğrenin.

Konumsal istekler

  • locations (zorunlu), yükseklik verilerinin döndürüleceği yerleri tanımlar. Bu parametre, virgülle ayrılmış {enlem,boylam} çifti olarak tek bir konum (ör. "40.714728,-73.998672") veya dizi ya da kodlanmış çoklu çizgi olarak iletilen birden fazla enlem/boylam çifti 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), yükseklik verilerinin döndürüleceği yeryüzündeki bir yolu tanımlar. Bu parametre, yeryüzünde bir yolu tanımlayan iki veya daha fazla sıralı {enlem,boylam} çiftinden oluşan bir grubu 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 nokta sayısını belirtir. samples parametresi, verilen path değerini yol boyunca eşit uzaklıkta bulunan sıralı 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 gösterir.

locations parametresi aşağıdaki bağımsız değişkenleri alabilir:

  • Tek bir koordinat: locations=40.714728,-73.998672
  • Dikey çizgi ("|") karakteriyle ayrılmış bir koordinat dizisi: locations=40.714728,-73.998672|-34.397,150.644
  • Encoded Polyline Algorithm kullanılarak kodlanmış bir dizi koordinat: locations=enc:gfo}EtohhU

Enlem ve boylam koordinat dizeleri, virgülle ayrılmış bir metin dizesindeki rakamlar kullanılarak tanımlanır. Örneğin, "40.714728,-73.998672" geçerli bir locations değeridir. Enlem ve boylam değerleri, yeryüzünde geçerli bir konuma karşılık gelmelidir. Enlem değerleri -90 ile 90 arasında, 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ı istek olarak reddedilir.

Geçerli bir URL oluşturmaya devam ederken bir dizi veya kodlanmış çoklu çizgi içinde en fazla 512 koordinat iletebilirsiniz. Birden fazla koordinat iletilirken döndürülen verilerin doğruluğunun, tek bir koordinat için veri isteğinde bulunulduğunda elde edilen verilerin doğruluğundan daha düşük çözünürlüklü olabileceğini unutmayın. "locations" veya "path" parametrelerinde 512 noktayı ya da koordinatı aşmak INVALID_REQUEST yanıtını döndürür.

Yolları belirtme

Örneklenmiş yol istekleri, belirtilen aralıklarla bir yol boyunca yükseklik verileri isteğini gösteren path ve samples parametreleri kullanılarak belirtilir. locations parametresinin kullanıldığı konuma dayalı isteklerde olduğu gibi, path parametresi de bir dizi enlem ve boylam değeri belirtir. Ancak konum isteğinden farklı olarak path, sıralı bir köşe kümesi belirtir. Yükseklik verilerini yalnızca köşelerde döndürmek yerine, yol istekleri samples belirtilen sayıya (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 ("|") karakteriyle ayrılmış, virgülle ayrılmış iki veya daha fazla koordinat metin dizesi dizisi: 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 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, yeryüzünde geçerli bir konuma karşılık gelmelidir. Enlem değerleri -90 ile 90 arasında, 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ı istek olarak reddedilir.

Geçerli bir URL oluşturmaya devam ederken bir dizi veya kodlanmış çoklu çizgi içinde en fazla 512 koordinat iletebilirsiniz. Birden fazla koordinat iletilirken döndürülen verilerin doğruluğunun, tek bir koordinat için veri isteğinde bulunulduğunda elde edilen verilerin doğruluğundan daha düşük çözünürlüklü olabileceğini unutmayın. "Konumlar" veya "yol" parametrelerinde 512 nokta ya da koordinatın aşılması INVALID_REQUEST yanıtı döndürür.

Rakım yanıtları

Yükseltme hizmeti, her geçerli istek için istek URL'sinde belirtilen biçimde bir Yükseltme 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ışında bir değer olduğunda, Elevation yanıt nesnesinde ek bir error_message alanı olabilir. Bu alan, verilen durum kodunun nedenleri hakkında daha ayrıntılı bilgiler içerir.

Yanıtta aşağıdaki öğeleri içeren bir results dizisi bulunur:

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 öğeleri içerir:

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, JSON biçiminde "Mile High City" (Bir Mil Yüksek Şehir) olarak bilinen Denver, Colorado'nun yüksekliği istenmektedir:

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 (Denver, CO ve Death Valley, CA için) gösterilmektedir.

Bu istekte, JSON output işaretinin kullanımı gösterilmektedir:

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 istekte, XML output işaretinin kullanımı gösterilmektedir:

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, ABD'nin en yüksek ve en alçak noktaları olan Kaliforniya'daki Whitney Dağı'ndan Kaliforniya'daki Badwater'a path düz bir çizgi boyunca yükseklik verileri istenmektedir. Üç samples istiyoruz. Bu nedenle iki uç nokta ve yarı yol noktası dahil edilir.

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>