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 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 (önerilir), JavaScript Nesne Gösterimi (JSON) biçiminde çıkışı gösterir veya
  • xml, 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 (&amp;) 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çı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 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 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ünyanın yüzeyindeki 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 parametresinin kullanıldığı 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ı

Her geçerli istek için Elevation hizmeti, istek URL'sinde belirtilen biçimde bir Elevation 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 öğ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, "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>