Panduan Developer

Google Maps Time Zone API menyediakan antarmuka sederhana untuk meminta zona waktu suatu lokasi di bumi, beserta perbedaan waktu lokasi itu dengan UTC.

Dokumen ini ditujukan untuk developer situs web dan seluler yang ingin menyertakan data waktu pada peta yang disediakan melalui salah satu Google Maps API. Dokumen ini menyediakan pengantar untuk menggunakan API dan materi referensi mengenai parameter yang tersedia.

Pengantar

Google Maps Time Zone API menyediakan data perbedaan waktu untuk semua lokasi di permukaan bumi. Anda meminta informasi zona waktu untuk pasangan garis lintang/bujur tertentu dan tanggalnya. API mengembalikan nama zona waktu, perbedaan waktu dari UTC, dan perbedaan waktu di musim panas.

Anda bisa mengakses Google Maps Time Zone API melalui antarmuka HTTP.

Sebelum Anda memulai development dengan Time Zone API, periksa persyaratan autentikasi (Anda memerlukan kunci API) dan batas penggunaan API.

Permintaan Zona Waktu

Permintaan Google Maps Time Zone API dibuat sebagai string URL. API mengembalikan data zona waktu untuk satu titik di bumi, yang ditetapkan melalui pasangan garis lintang/bujur.. Perhatikan, data zona waktu mungkin tidak tersedia untuk lokasi di atas air, misalnya samudra atau lautan.

Permintaan Google Maps Time Zone API mengambil bentuk berikut:

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

dalam hal ini, outputFormat bisa berupa salah satu nilai berikut:

• json (disarankan), menunjukkan keluaran dalam JavaScript Object Notation (JSON); atau
• xml, menunjukkan keluaran dalam XML, yang dimasukkan di dalam simpul <TimeZoneResponse>.

Penting: Anda harus mengirimkan permintaan melalui https, bukan http.

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

Parameter Permintaan

Sebagaimana standar dalam semua URL, parameter dipisah menggunakan karakter ampersand (&). Daftar parameter dan kemungkinan nilainya ditunjukkan di bawah ini.

Parameter yang Diperlukan

• location: tuple garis lintang,garis bujur yang dipisah koma (mis. location=-33.86,151.20), menyatakan yang akan dicari.
• timestamp menetapkan waktu yang diinginkan dalam detik sejak tengah malam, 1 Januari 1970 UTC. Google Maps Time Zone API menggunakan timestamp untuk menentukan apakah Waktu di Musim Panas harus diterapkan atau tidak. Waktu sebelum tahun 1970 bisa dinyatakan berupa nilai negatif.
• key — Kunci API aplikasi Anda. Kunci ini mengidentifikasi aplikasi Anda untuk keperluan manajemen kuota. Pelajari cara mendapatkan kunci.

  Catatan: Pelanggan Google Maps APIs Premium Plan bisa memilih menggunakan kunci API atau ID klien dan tanda tangan digital yang valid, di permintaan Time Zone Anda. Dapatkan informasi selengkapnya tentang parameter autentikasi untuk pelanggan Premium Plan.

Parameter Opsional

• language — Bahasa yang digunakan untuk mengembalikan hasil. Lihat daftar bahasa domain yang didukung. Perhatikan, kami sering memperbarui bahasa yang didukung sehingga daftar ini mungkin tidak lengkap. Default-nya adalah en.

Respons Zona Waktu

Untuk setiap permintaan yang valid, layanan zona waktu akan mengembalikan respons zona waktu dalam format yang ditunjukkan dalam URL permintaan. Setiap respons akan berisi elemen-elemen berikut:

• dstOffset: perbedaan waktu di musim panas dalam detik. Nilai ini akan nol jika zona waktu tidak dalam Waktu Musim Panas selama timestamp yang ditetapkan.
• rawOffset: perbedaan dari UTC (dalam detik) untuk lokasi yang diberikan. Ini tidak akan memengaruhi waktu di musim panas.
• timeZoneId: string berisi ID zona waktu "tz", misalnya "America/Los_Angeles" atau "Australia/Sydney". ID ini didefinisikan dalam Database Zona Waktu IANA, yang juga tersedia dalam format yang bisa ditelusuri dalam Daftar zona waktu database tz Wikipedia.
• timeZoneName: string yang berisi format panjang nama zona waktu. Bidang ini akan dilokalkan jika parameter bahasa telah disetel, misalnya "Pacific Daylight Time" atau "Australian Eastern Daylight Time"
• status: string yang menunjukkan status respons.
  • OK menunjukkan permintaan berhasil.
  • INVALID_REQUEST menunjukkan format permintaan salah.
  • OVER_QUERY_LIMIT menunjukkan pemohon telah melebihi kuota.
  • REQUEST_DENIED menunjukkan API tidak melakukan permintaan. Mengonfirmasi bahwa permintaan tersebut dikirim melalui HTTPS sebagai ganti HTTP.
  • UNKNOWN_ERROR menunjukkan kesalahan yang tidak diketahui.
  • ZERO_RESULTS menunjukkan data zona waktu tidak bisa ditemukan untuk posisi atau waktu yang ditetapkan. Mengonfirmasi bahwa permintaan tersebut adalah untuk lokasi di atas tanah, bukan di atas air.
• error_message: informasi lebih detail tentang alasan di balik kode status yang diberikan, jika bukan OK.

  Catatan: Bidang ini tidak dijamin akan selalu ada, dan materinya bisa berubah.

Menghitung Waktu Lokal

Waktu lokal untuk lokasi yang diberikan adalah jumlah parameter timestamp, dan bidang dstOffset serta bidang rawOffset dari hasilnya.

Contoh Permintaan

Bagian ini berisi beberapa kueri contoh yang memperagakan fitur-fitur API.

Kueri berikut ini melakukan permintaan zona waktu untuk Nevada, AS. Cap waktu disetel ke 8 Maret 2012.

https://maps.googleapis.com/maps/api/timezone/json?location=39.6034810,-119.6822510&timestamp=1331161200&key=YOUR_API_KEY

{
   "dstOffset" : 0,
   "rawOffset" : -28800,
   "status" : "OK",
   "timeZoneId" : "America/Los_Angeles",
   "timeZoneName" : "Pacific Standard Time"
}
    

https://maps.googleapis.com/maps/api/timezone/xml?location=39.6034810,-119.6822510&timestamp=1331161200&key=YOUR_API_KEY

<TimeZoneResponse>
  <status>OK</status>
  <raw_offset>-28800.0000000</raw_offset>
  <dst_offset>0.0000000</dst_offset>
  <time_zone_id>America/Los_Angeles</time_zone_id>
  <time_zone_name>Pacific Standard Time</time_zone_name>
</TimeZoneResponse>

Kueri berikut ini melakukan permintaan zona waktu untuk Nevada, AS. Lokasinya sama dengan permintaan di atas, namun cap waktunya disetel ke 15 Maret 2012. Responsnya sekarang menyertakan offset Selisih Waktu di Musim Panas.

https://maps.googleapis.com/maps/api/timezone/json?location=39.6034810,-119.6822510&timestamp=1331766000&key=YOUR_API_KEY

{
   "dstOffset" : 3600,
   "rawOffset" : -28800,
   "status" : "OK",
   "timeZoneId" : "America/Los_Angeles",
   "timeZoneName" : "Pacific Daylight Time"
}
    

https://maps.googleapis.com/maps/api/timezone/xml?location=39.6034810,-119.6822510&timestamp=1331766000&key=YOUR_API_KEY

<TimeZoneResponse>
  <status>OK</status>
  <raw_offset>-28800.0000000</raw_offset>
  <dst_offset>3600.0000000</dst_offset>
  <time_zone_id>America/Los_Angeles</time_zone_id>
  <time_zone_name>Pacific Daylight Time</time_zone_name>
</TimeZoneResponse>

Contoh ini sama dengan kedua contoh di atas, namun parameter bahasa telah disetel. Responsnya sekarang akan dilokalkan ke bahasa Spanyol.

https://maps.googleapis.com/maps/api/timezone/json?location=39.6034810,-119.6822510&timestamp=1331766000&language=es&key=YOUR_API_KEY

{
   "dstOffset" : 3600,
   "rawOffset" : -28800,
   "status" : "OK",
   "timeZoneId" : "America/Los_Angeles",
   "timeZoneName" : "Hora de verano del Pacífico"
}
    

https://maps.googleapis.com/maps/api/timezone/xml?location=39.6034810,-119.6822510&timestamp=1331766000&language=es&key=YOUR_API_KEY

<TimeZoneResponse>
  <status>OK</status>
  <raw_offset>-28800.0000000</raw_offset>
  <dst_offset>3600.0000000</dst_offset>
  <time_zone_id>America/Los_Angeles</time_zone_id>
  <time_zone_name>Hora de verano del Pacífico</time_zone_name>
</TimeZoneResponse>

Parameter sensor

Google Maps API sebelumnya mengharuskan Anda menyertakan parameter sensor untuk menunjukkan apakah aplikasi Anda menggunakan sensor untuk menentukan lokasi pengguna. Parameter ini tidak lagi diperlukan.