Yükseklik istekleri ve yanıtları

Yükselti istekleri

Elevation API istekleri bir URL dizesi olarak oluşturulur. API, dünyadaki konumlara ait yükseklik verilerini döndürür. Konum verilerini iki yöntemden birini kullanarak belirleyebilirsiniz:

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

Bu yaklaşımlardan her ikisi de konumları veya yolun köşe noktalarını belirlemek 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 verileri mümkün olan en yüksek doğrulukta döndürür. Birden fazla konum içeren toplu sorgular, daha az doğrulukla veri döndürebilir, özellikle de verilerde bazı düzgünleştirme işlemleri gerçekleştiğinden konumlar birbirinden ayrıysa.

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 (önerilen), çıkışı JavaScript Object Notation (JSON) biçiminde belirtir veya
  • xml, çıkışı XML biçiminde gösterir, bir <ElevationResponse> düğümü içinde sarmalanmış durumdadır.

Not: URL'ler, geçerli olmaları için doğru şekilde kodlanmalı ve tüm web hizmetleri için 16.384 karakterle sınırlı olmalı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ına sahip olabileceğini unutmayın.

API anahtarı kullanan istekler için HTTPS gereklidir.

İstek parametreleri

Elevation API'ye yapılan istekler, isteğin ayrı konumlara mı yoksa sıralı bir yol için mi olduğuna bağlı olarak farklı parametreler kullanır. Ayrı konumlar için istekte geçirilen belirli konumlar hakkında yükseklik verisi istekleri; yollar için ise yükseklik istekleri, bunun yerine belirtilen 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 talepler

  • key — (zorunlu) Uygulamanızın API anahtarı. Bu anahtar, kota yönetimi amaçları doğrultusunda 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 ya da 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 bölümüne bakın.

Örneklenen yol istekleri

  • path (zorunlu), dünya üzerinde yükseklik verilerinin döndürüleceği bir yolu tanımlar. Bu parametre, dünyanın yüzeyi boyunca bir yolu 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 yoldaki yükseklik verilerinin döndürülmesi için örnek noktalarının sayısını belirtir. samples parametresi, verilen path değerini yol boyunca sıralı bir eşit uzaklıkta nokta grubuna böler.

Yerleri belirtme

Konumsal istekler, locations parametresi kullanılarak belirtilir ve 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ış koordinat dizisi: locations=40.714728,-73.998672|-34.397,150.644
  • Kodlanmış Çoklu Çizgi Algoritması kullanan kodlanmış koordinat dizisi: locations=enc:gfo}EtohhU

Enlem ve boylam koordinat dizeleri, virgülle ayrılmış bir metin dizesinde yer alan 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 yüzeyindeki geçerli bir konuma karşılık gelmelidir. Enlemler -90 ile 90 arasındaki her değeri alabilirken boylam değerleri, -180 ile 180 arasındaki 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ştururken bir dizi veya kodlanmış çoklu çizgi içinde en fazla 512 koordinat iletebilirsiniz. Birden fazla koordinatları geçirirken, döndürülen verilerin doğruluğunun, tek bir koordinat için veri isteğinde bulunurken 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

Örneklenen yol istekleri, path ve samples parametrelerinin kullanımıyla belirtilir. Bu, bir yol boyunca belirli aralıklarla yükseklik verisi isteğini belirtir. locations parametresini kullanan konum isteklerinde olduğu gibi path parametresi de bir dizi enlem ve boylam değeri belirtir. Bununla birlikte, konumsal istekten farklı olarak path, sıralı bir köşe noktası grubu belirtir. Yalnızca köşelerde yükseklik verileri döndürmek yerine, yol istekleri, belirtilen samples sayısına (uç noktalar dahil) bağlı olarak yol uzunluğu 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 virgülle ayrılmış 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 dizesinde yer alan 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 yüzeyindeki geçerli bir konuma karşılık gelmelidir. Enlemler -90 ile 90 arasındaki her değeri alabilirken boylam değerleri, -180 ile 180 arasındaki 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ştururken bir dizi veya kodlanmış çoklu çizgi içinde en fazla 512 koordinat iletebilirsiniz. Birden fazla koordinat aktarılırken, döndürülen verilerin doğruluğunun, tek bir koordinat için veri isteğinde bulunurken 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.

Yükseklik yanıtları

Yükseklik hizmeti, geçerli her 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ışında olduğunda Yükseklik yanıt nesnesinin içinde 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çeriyor:

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 Denver, Colorado, "Mile High City" için yükselti değeri JSON biçiminde 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ımı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 kullanımını göstermektedir:

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, Kaliforniya Dağı'ndan Badwater, Kaliforniya'ya uzanan düz bir çizgi boyunca path kıtası ABD'nin en yüksek ve en düşük noktaları olan yükseklik verileri talep edilmektedir. Üç tane samples istiyoruz. Bu yüzden bu, iki uç noktayı ve yarım noktayı içerir.

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>