Permintaan dan respons Zona Waktu

Zona Waktu

Permintaan Time Zone API dibuat sebagai string URL. API ini menampilkan data zona waktu untuk suatu titik di bumi, yang ditentukan oleh pasangan lintang-bujur. Perhatikan bahwa data zona waktu mungkin tidak tersedia untuk lokasi di atas air, seperti samudra atau laut.

Permintaan Time Zone memiliki format berikut:

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

dengan outputFormat dapat berupa salah satu dari nilai berikut:

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

Parameter yang diperlukan

lokasi

Tuple lintang,bujur yang dipisahkan koma, location=39.6034810,-119.6822510, yang mewakili lokasi yang akan dicari.

timestamp

Waktu yang diinginkan dalam detik sejak tengah malam, 1 Januari 1970 UTC. Time Zone API menggunakan timestamp untuk menentukan apakah Waktu Musim Panas harus diterapkan atau tidak, berdasarkan zona waktu location.

Perhatikan bahwa API tidak memperhitungkan zona waktu historis. Artinya, jika Anda menentukan stempel waktu yang sudah berlalu, API tidak akan memperhitungkan kemungkinan bahwa lokasi tersebut sebelumnya berada di zona waktu yang berbeda.

Parameter opsional

bahasa

Bahasa yang digunakan untuk menampilkan hasil.

  • Lihat daftar bahasa yang didukung. Google sering memperbarui bahasa yang didukung, sehingga daftar ini mungkin tidak lengkap.
  • Jika language tidak diberikan, API akan mencoba menggunakan bahasa pilihan seperti yang ditentukan dalam header Accept-Language.
  • API ini melakukan yang terbaik untuk memberikan alamat yang dapat dibaca oleh pengguna dan penduduk setempat. Untuk mencapai sasaran tersebut, API ini menampilkan alamat jalan dalam bahasa lokal, yang ditransliterasikan ke skrip yang dapat dibaca oleh pengguna jika perlu, dengan mengamati bahasa pilihan. Semua alamat lainnya ditampilkan dalam bahasa pilihan. Komponen alamat semuanya ditampilkan dalam bahasa yang sama, yang dipilih dari komponen pertama.
  • Jika nama tidak tersedia dalam bahasa pilihan, API akan menggunakan kecocokan terdekat.
  • Bahasa pilihan memiliki pengaruh kecil pada kumpulan hasil yang dipilih API untuk ditampilkan, dan urutan kemunculannya. Geocoder menafsirkan singkatan secara berbeda bergantung pada bahasa, seperti singkatan untuk jenis jalan, atau sinonim yang mungkin valid dalam satu bahasa, tetapi tidak dalam bahasa lain. Misalnya, utca dan tér adalah sinonim untuk jalan dalam bahasa Hungaria.

Contoh Zona Waktu

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

Kueri berikut ini melakukan permintaan zona waktu untuk Nevada, AS. Stempel waktu ditetapkan ke 5 Desember 2024.

URL

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

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/timezone/json?location=39.6034810,-119.6822510&timestamp=1733428634&key=YOUR_API_KEY'

JSON

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

XML

<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, tetapi stempel waktunya ditetapkan ke 15 Maret 2024. Respons kini menyertakan selisih Waktu Musim Panas.

URL

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

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/timezone/json?location=39.6034810,-119.6822510&timestamp=1710547034&key=YOUR_API_KEY'

JSON

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

XML

<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. Respons akan dilokalkan ke bahasa Spanyol.

URL

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

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/timezone/json?location=39.6034810,-119.6822510&timestamp=1710547034&language=es&key=YOUR_API_KEY'

JSON

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

XML

<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>

Respons Zona Waktu

Untuk setiap permintaan yang valid, Time Zone akan menampilkan respons dalam format yang ditunjukkan dalam URL permintaan.

TimeZoneResponse

Kolom Wajib Jenis Deskripsi
required TimeZoneStatus Lihat TimeZoneStatus untuk mengetahui informasi selengkapnya.
opsional angka

Selisih untuk waktu musim panas dalam detik. Nilai ini akan menjadi nol jika zona waktu tidak berada dalam Waktu Musim Panas selama timestamp yang ditentukan.

opsional string

Informasi mendetail tentang alasan di balik kode status yang diberikan. Disertakan jika status selain Ok.

opsional angka

Selisih dari UTC (dalam detik) untuk lokasi tertentu. Hal ini tidak memperhitungkan waktu musim panas.

opsional string

string yang berisi ID zona waktu, seperti "America/Los_Angeles" atau "Australia/Sydney". ID ini ditentukan oleh project Unicode Common Locale Data Repository (CLDR), dan saat ini tersedia dalam file timezone.xml. Jika zona waktu memiliki beberapa ID, ID kanonis akan ditampilkan. Dalam respons xml, ini adalah alias pertama dari setiap zona waktu. Misalnya, "Asia/Calcutta" ditampilkan, bukan "Asia/Kolkata".

opsional string

Nama panjang zona waktu. Kolom ini akan dilokalkan jika parameter bahasa ditetapkan. Misalnya, Pacific Daylight Time atau Australian Eastern Daylight Time.

TimeZoneStatus

Kolom status dalam objek respons zona waktu berisi status permintaan. Kolom status dapat berisi nilai berikut:

  • OK menunjukkan bahwa permintaan berhasil.

  • INVALID_REQUEST menunjukkan bahwa permintaan memiliki format yang salah.

  • OVER_DAILY_LIMIT menunjukkan salah satu hal berikut:

    • Kunci API tidak ada atau tidak valid.
    • Penagihan belum diaktifkan di akun Anda.
    • Batas penggunaan yang ditentukan sendiri telah terlampaui.
    • Metode pembayaran yang diberikan sudah tidak valid (misalnya kartu kredit yang sudah tidak berlaku).

  • OVER_QUERY_LIMIT menunjukkan bahwa pemohon telah melampaui kuota.

  • REQUEST_DENIED menunjukkan bahwa API tidak menyelesaikan permintaan. Mengonfirmasi bahwa permintaan tersebut dikirim melalui HTTPS sebagai ganti HTTP.

  • UNKNOWN_ERROR menunjukkan error yang tidak diketahui.

  • ZERO_RESULTS menunjukkan bahwa tidak ada data zona waktu yang dapat ditemukan untuk posisi atau waktu yang ditentukan. Pastikan bahwa permintaan tersebut ditujukan untuk lokasi di darat, bukan di perairan.

Menghitung waktu lokal

Waktu lokal lokasi tertentu adalah jumlah parameter timestamp, serta kolom dstOffset dan rawOffset dari hasil.