Permintaan dan respons Zona Waktu

Zona Waktu

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

Permintaan Zona Waktu menggunakan format berikut:

https://maps.googleapis.com/maps/api/timezone/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 dienkapsulasi dalam node <TimeZoneResponse>.

Catatan: URL harus dienkode dengan benar agar 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 juga.

Parameter yang diperlukan

  • lokasi

    Tuple latitude,bujur yang dipisahkan koma, location=39.6034810,-119.6822510, yang merepresentasikan 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 mempertimbangkan kemungkinan bahwa lokasi tersebut sebelumnya berada di zona waktu yang berbeda.

Parameter opsional

  • language

    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 berupaya sebaik mungkin untuk memberikan alamat jalan yang dapat dibaca oleh pengguna dan penduduk setempat. Untuk mencapai tujuan tersebut, API ini menampilkan alamat jalan dalam bahasa lokal, yang ditransliterasi ke skrip yang dapat dibaca oleh pengguna jika perlu, dengan memperhatikan 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 sedikit pengaruh pada kumpulan hasil yang dipilih API untuk ditampilkan, dan urutan penampilannya. 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%2C-119.6822510
  ×tamp=1733428634
  &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/timezone/json?location=39.6034810%2C-119.6822510×tamp=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. Responsnya sekarang menyertakan offset Selisih Waktu di Musim Panas.

URL

https://maps.googleapis.com/maps/api/timezone/json
  ?location=39.6034810%2C-119.6822510
  ×tamp=1710547034
  &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/timezone/json?location=39.6034810%2C-119.6822510×tamp=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. Responsnya sekarang akan dilokalkan ke bahasa Spanyol.

URL

https://maps.googleapis.com/maps/api/timezone/json
  ?language=es
  &location=39.6034810%2C-119.6822510
  ×tamp=1710547034
  &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/timezone/json?location=39.6034810%2C-119.6822510×tamp=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 API akan menampilkan respons dalam format yang ditunjukkan dalam URL permintaan.

TimeZoneResponse

Kolom Wajib Jenis Deskripsi
wajib ada TimeZoneStatus Lihat TimeZoneStatus untuk 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. Durasi 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 di file timezone.xml. Jika zona waktu memiliki beberapa ID, ID kanonis akan ditampilkan. Dalam respons xml, ini adalah alias pertama setiap zona waktu. Misalnya, "Asia/Calcutta" akan 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 format permintaan 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. Konfirmasi bahwa permintaan ditujukan untuk lokasi di darat, dan bukan di atas air.

Menghitung waktu setempat

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