Halaman ini diterjemahkan oleh Cloud Translation API.

Respons dan permintaan elevasi

Permintaan elevasi

Permintaan Elevation API dibuat sebagai string URL. API mengembalikan data elevasi untuk semua lokasi di permukaan bumi. Anda menentukan data lokasi melalui salah satu dari dua cara berikut:

Sebagai kumpulan dari satu atau beberapa locations.
Sebagai serangkaian titik yang terhubung di sepanjang path.

Kedua pendekatan ini menggunakan koordinat lintang/bujur untuk mengidentifikasi lokasi atau verteks jalur. Dokumen ini menjelaskan format URL Elevation API yang diperlukan dan parameter yang tersedia.

Elevation API menampilkan data untuk kueri satu titik dengan kemungkinan akurasi tertinggi. Kueri batch yang melibatkan beberapa lokasi mungkin menampilkan data dengan akurasi yang lebih rendah, terutama jika lokasinya tersebar jauh, karena terjadi penghalusan data.

Permintaan Elevation API mengambil bentuk berikut:

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

dengan outputFormat dapat berupa salah satu nilai berikut:

json (direkomendasikan), menunjukkan output dalam JavaScript Object Notation (JSON); atau
xml, menunjukkan output dalam XML, yang digabungkan dalam node <ElevationResponse>.

Catatan: URL harus dienkode dengan benar valid dan dibatasi hingga 16.384 karakter untuk semua layanan web. Perhatikan batas ini saat membuat URL Anda. Perhatikan bahwa browser, proxy, dan server yang berbeda mungkin memiliki batas karakter URL yang berbeda pula.

HTTPS diperlukan untuk permintaan yang menggunakan kunci API.

Parameter permintaan

Permintaan ke Elevation API menggunakan parameter yang berbeda berdasarkan apakah permintaan tersebut ditujukan untuk lokasi diskret jalur yang diurutkan. Untuk lokasi yang terpisah, permintaan elevasi akan menampilkan data tentang lokasi tertentu yang diteruskan dalam permintaan; untuk jalur, permintaan elevasi akan diambil sampelnya di sepanjang jalur yang diberikan.

Sesuai dengan standar di semua URL, parameter dipisahkan menggunakan karakter ampersand (&). Daftar parameter dan kemungkinan nilainya ditunjukkan di bawah ini.

Semua permintaan

key — (wajib) Kunci API aplikasi Anda. Kunci ini mengidentifikasi aplikasi Anda untuk keperluan manajemen kuota. Pelajari cara mendapatkan kunci.

Permintaan posisi

locations (diperlukan) menentukan lokasi di atas bumi yang menjadi titik ditampilkannya data elevasi. Parameter ini mengambil satu lokasi sebagai pasangan {latitude,longitude} yang dipisahkan koma (misalnya "40.714728,-73.998672") atau beberapa pasangan lintang/bujur yang diteruskan sebagai array atau sebagai polyline yang dienkode. Ada batas 512 titik untuk parameter khusus ini. Untuk informasi selengkapnya, lihat Menentukan Lokasi di bawah.

Contoh permintaan jalur

path (wajib) menentukan jalur di atas bumi yang data elevasinya akan ditampilkan. Parameter ini menentukan sekumpulan dua atau beberapa pasangan {latitude,longitude} terurut yang menentukan jalur di sepanjang permukaan bumi. Parameter ini harus digunakan bersama samples parameter yang dijelaskan di bawah ini. Ada batas 512 poin untuk parameter spesifik. Untuk informasi selengkapnya, lihat Menetapkan Jalur di bawah.
samples (diperlukan) menentukan jumlah titik sampel di sepanjang jalur yang data elevasinya akan ditampilkan. Tujuan Parameter samples membagi path yang ditentukan menjadi satu set titik yang berjarak sama di sepanjang jalur.

Menentukan lokasi

Permintaan posisi ditunjukkan melalui penggunaan Parameter locations, yang menunjukkan permintaan elevasi untuk lokasi tertentu yang diteruskan sebagai nilai lintang/bujur.

Parameter locations dapat mengambil hal berikut argumen:

Satu koordinat: locations=40.714728,-73.998672
Array koordinat yang dipisahkan menggunakan pipa ('|') karakter: locations=40.714728,-73.998672|-34.397,150.644
Satu set koordinat yang dienkode menggunakan atribut Dienkode Algoritme Polyline: locations=enc:gfo}EtohhU

String koordinat lintang dan bujur didefinisikan menggunakan angka dalam string teks yang dipisahkan koma. Misalnya, "40.714728,-73.998672" adalah nilai locations yang valid. Lintang dan nilai bujur harus sesuai dengan lokasi yang valid di permukaan bumi. Lintang dapat mengambil nilai apa pun antara -90 dan 90, sedangkan nilai bujur bisa memakan waktu nilai apa pun antara -180 dan 180. Jika Anda menentukan nilai lintang atau bujur yang tidak valid, permintaan Anda akan ditolak sebagai permintaan yang buruk.

Anda dapat meneruskan hingga 512 koordinat dalam array atau polyline yang dienkode, sambil tetap membuat URL yang valid. Perhatikan, saat meneruskan beberapa koordinat, akurasi data yang ditampilkan mungkin memiliki resolusi lebih rendah daripada saat meminta data untuk satu koordinat. Melebihi 512 titik atau koordinat dalam parameter 'locations' atau 'path' akan menampilkan respons INVALID_REQUEST.

Menentukan jalur

Contoh permintaan jalur ditunjukkan melalui penggunaan path dan parameter samples, yang menunjukkan permintaan untuk data elevasi sepanjang jalur pada interval tertentu. Seperti permintaan posisi yang menggunakan parameter locations, parameter path menentukan sekumpulan nilai lintang dan bujur. Namun, tidak seperti permintaan posisi, path menentukan kumpulan verteks yang diurutkan. Bukannya mengembalikan data elevasi hanya pada verteks, permintaan jalur diambil sampelnya di sepanjang panjang jalur, berdasarkan jumlah samples yang ditentukan (termasuk endpoint).

Parameter path dapat menggunakan salah satu argumen berikut:

Array dari dua atau beberapa string teks koordinat yang dipisahkan koma dipisahkan menggunakan pipa ('|') karakter: path=40.714728,-73.998672|-34.397,150.644
Koordinat yang dienkode menggunakan Algoritme Polyline yang Dienkode: path=enc:gfo}EtohhUxD@bAxJmGF

String koordinat lintang dan bujur didefinisikan menggunakan angka dalam string teks yang dipisahkan koma. Misalnya, "40.714728,-73,998672|-34,397, 150,644" adalah valid Nilai path. Nilai lintang dan bujur harus sesuai ke lokasi yang valid di permukaan bumi. Lintang dapat mengambil nilai apa pun antara -90 dan 90, sedangkan nilai bujur bisa memakan waktu nilai apa pun antara -180 dan 180. Jika Anda menentukan nilai lintang atau bujur yang tidak valid, permintaan Anda akan ditolak sebagai permintaan yang buruk.

Anda dapat meneruskan hingga 512 koordinat dalam array atau polyline yang dienkode, sambil tetap membuat URL yang valid. Perhatikan bahwa saat meneruskan beberapa koordinat, akurasi data yang ditampilkan mungkin memiliki resolusi lebih rendah daripada saat meminta data untuk satu koordinat. Melebihi 512 titik atau koordinat di 'lokasi' atau 'path' (jalur) parameter menampilkan respons INVALID_REQUEST.

Respons elevasi

Untuk setiap permintaan yang valid, layanan Elevation akan menampilkan respons Elevation dalam format yang ditunjukkan dalam URL permintaan.

ElevationResponse

Field	Required	Type	Description
`results`	required	Array<ElevationResult>	See ElevationResult for more information.
`status`	required	ElevationStatus	See ElevationStatus for more information.
`error_message`	optional	string	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.

Jika kode status selain OK, mungkin ada kode status tambahan Kolom error_message dalam objek respons Elevation. Bidang ini berisi lebih banyak informasi mendetail tentang alasan di balik kode status yang diberikan.

Respons berisi array results dengan elemen berikut:

ElevationResult

Field	Required	Type	Description
`elevation`	required	number	The elevation of the location in meters.
`location`	required	LatLngLiteral	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.
`resolution`	optional	number	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.

Objek location memiliki elemen berikut:

LatLngLiteral

An object describing a specific location with Latitude and Longitude in decimal degrees.

Field	Required	Type	Description
`lat`	required	number	Latitude in decimal degrees
`lng`	required	number	Longitude in decimal degrees

Contoh elevasi posisi

Contoh berikut meminta elevasi untuk Denver, Colorado, "Mile High City" dalam format JSON:

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>

Contoh berikut menampilkan beberapa respons (untuk Denver, CO dan untuk Death Valley, CA).

Permintaan ini menunjukkan penggunaan flag output JSON:

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'

Permintaan ini menunjukkan penggunaan flag output XML:

https://maps.googleapis.com/maps/api/elevation/xml?locations=39.7391536,-104.9847034|36.455556,-116.866667&key=YOUR_API_KEY

Pilih tab di bawah ini untuk melihat contoh respons JSON dan XML.

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>

Contoh berikut meminta data elevasi sepanjang garis lurus path dari Mt. Whitney, CA ke Badwater, CA, tertinggi dan titik terendah di benua Amerika Serikat. Kita meminta tiga samples, sehingga akan menyertakan dua titik akhir dan titik separuh jalan.

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>

Respons dan permintaan elevasi

Permintaan elevasi

Parameter permintaan

Semua permintaan

Permintaan posisi

Contoh permintaan jalur

Menentukan lokasi

Menentukan jalur

Respons elevasi

ElevationResponse

`results`

`status`

`error_message`

ElevationStatus

ElevationResult

`elevation`

`location`

`resolution`

LatLngLiteral

`lat`

`lng`

Contoh elevasi posisi

URL

cURL

JSON

XML

URL

cURL

JSON

XML

URL

cURL

JSON

XML