Permintaan elevasi
Permintaan Elevation API dibuat sebagai string URL. API menampilkan data elevasi untuk semua lokasi di permukaan bumi. Anda menentukan data lokasi dengan 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 yang diperlukan untuk URL Elevation API dan parameter yang tersedia.
Elevation API menampilkan data untuk kueri titik tunggal dengan akurasi setinggi mungkin. Kueri batch yang melibatkan beberapa lokasi dapat menampilkan data dengan akurasi yang kurang akurat, terutama jika lokasi tersebar secara terpisah, saat terjadi kelancaran 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); atauxml
, menunjukkan output dalam XML, yang digabungkan dalam node<ElevationResponse>
.
Catatan: URL harus dienkode dengan benar agar valid dan dibatasi hingga 16.384 karakter untuk semua layanan web. Perhatikan batasan ini saat membuat URL Anda. Perhatikan bahwa browser, proxy, dan server yang berbeda mungkin juga memiliki batas karakter URL yang berbeda.
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 terpisah atau untuk 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 dipisah
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
(wajib) 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 garis lintang/bujur yang diteruskan sebagai array atau sebagai polyline yang dienkode. Ada batas 512 poin untuk parameter khusus ini. Untuk informasi selengkapnya, lihat Menentukan Lokasi di bawah.
Contoh permintaan jalur
path
(diperlukan) menentukan jalur di atas bumi yang akan digunakan untuk menampilkan data elevasi. Parameter ini menentukan kumpulan dua atau beberapa pasangan {latitude,longitude} yang diurutkan yang menentukan jalur di sepanjang permukaan bumi. Parameter ini harus digunakan bersama dengan parametersamples
yang dijelaskan di bawah. Ada batas 512 poin untuk parameter khusus ini. Untuk informasi selengkapnya, lihat Menentukan Jalur di bawah.samples
(diperlukan) menetapkan jumlah titik sampel di sepanjang jalur yang data elevasinya akan tampilkan. Parametersamples
membagipath
yang diberikan ke dalam kumpulan titik yang berjarak sama secara berurutan 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 menerima argumen
berikut:
- Satu koordinat:
locations=40.714728,-73.998672
- Array koordinat yang dipisah menggunakan karakter pipa ('
|
'):locations=40.714728,-73.998672|-34.397,150.644
- Serangkaian koordinat yang dienkode menggunakan Algoritma Polyline yang Dienkode:
locations=enc:gfo}EtohhU
String koordinat lintang dan bujur ditentukan menggunakan angka
dalam string teks yang dipisahkan koma. Misalnya, "40.714728,-73.998672"
adalah nilai locations
yang valid. Nilai garis lintang dan garis bujur harus sesuai dengan lokasi yang valid di permukaan bumi. Lintang dapat bernilai apa pun antara
-90
dan 90
, sedangkan nilai bujur dapat berupa
nilai apa pun antara -180
dan 180
. Jika Anda menetapkan 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 'lokasi' atau 'jalur' akan menampilkan respons INVALID_REQUEST
.
Menentukan jalur
Permintaan sampel jalur ditunjukkan melalui penggunaan parameter path
dan samples
, yang menunjukkan permintaan untuk data elevasi
di sepanjang jalur pada interval tertentu. Seperti permintaan posisi yang menggunakan parameter locations
, parameter path
menetapkan sekumpulan nilai garis lintang dan garis bujur. Namun, tidak seperti permintaan posisi, path
menentukan kumpulan verteks yang diurutkan. Daripada menampilkan data elevasi hanya di verteks, sampel permintaan jalur diambil di sepanjang jalur, berdasarkan jumlah samples
yang ditentukan (termasuk endpoint).
Parameter path
dapat mengambil salah satu argumen berikut:
- Array berisi dua atau beberapa string teks koordinat yang dipisahkan koma
yang dipisahkan menggunakan karakter pipa ('
|
'):path=40.714728,-73.998672|-34.397,150.644
- Koordinat yang dienkode menggunakan Algoritma Polyline yang Dienkode:
path=enc:gfo}EtohhUxD@bAxJmGF
String koordinat lintang dan bujur ditentukan menggunakan angka
dalam string teks yang dipisahkan koma. Misalnya,
"40.714728,-73.998672|-34.397, 150.644" adalah nilai
path
yang valid. Nilai garis lintang dan garis bujur harus sesuai dengan lokasi yang valid di permukaan bumi. Lintang dapat bernilai apa pun antara
-90
dan 90
, sedangkan nilai bujur dapat berupa
nilai apa pun antara -180
dan 180
. Jika Anda menetapkan 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 'lokasi' atau 'jalur' akan 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 |
---|---|---|---|
| required | Array<ElevationResult> | See ElevationResult for more information. |
| required | ElevationStatus | See ElevationStatus for more information. |
| optional | string |
When the service returns a status code other than |
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 kolom
error_message
tambahan dalam objek respons Elevation. Kolom ini berisi informasi
mendetail tentang alasan di balik kode status yang diberikan.
Respons berisi array results
dengan elemen berikut:
ElevationResult
Field | Required | Type | Description |
---|---|---|---|
| required | number | The elevation of the location in meters. |
| 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. |
| 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 |
---|---|---|---|
| required | number | Latitude in decimal degrees |
| 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 menunjukkan beberapa respons (untuk Denver, CO dan untuk Death Valley, CA).
Permintaan ini menunjukkan penggunaan tanda 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 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, titik tertinggi dan
terendah di benua Amerika Serikat. Kita meminta tiga
samples
, sehingga akan menyertakan dua endpoint dan
titik setengah.
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>