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 air, seperti lautan atau samudra.

Permintaan Zona Waktu memiliki 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. Perhatikan bahwa browser, proxy, dan server yang berbeda mungkin memiliki batas karakter URL yang berbeda juga.

Parameter yang diperlukan

  • lokasi

    Tuple garis 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 sebelumnya, API tidak akan memperhitungkan 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 akan berupaya sebaik mungkin untuk memberikan alamat jalan yang dapat dibaca oleh pengguna dan penduduk setempat. Untuk mencapai tujuan tersebut, API akan menampilkan alamat jalan dalam bahasa lokal, yang ditransliterasi ke skrip yang dapat dibaca oleh pengguna jika diperlukan, dengan memperhatikan bahasa pilihan. Semua alamat lainnya ditampilkan dalam bahasa pilihan. Semua komponen alamat 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 hasil tersebut ditampilkan. 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 waktu ditetapkan ke 15 Maret 2024. Respons kini menyertakan selisih waktu 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 kini 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, Zona Waktu akan menampilkan respons dalam format yang ditunjukkan dalam URL permintaan.

TimeZoneResponse

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

Offset 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

Offset dari UTC (dalam detik) untuk lokasi yang diberikan. Hal ini tidak berlaku untuk 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 zona waktu dalam bentuk panjang. 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 permintaan ditujukan untuk a lokasi di darat, bukan di atas air.

Menghitung waktu lokal

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