คำขอและการตอบกลับเขตเวลา

เขตเวลา

คำขอ Time Zone API จะสร้างขึ้นเป็นสตริง URL API จะแสดงผลข้อมูลเขตเวลาสำหรับจุดบนโลกที่ระบุโดยคู่ละติจูด-ลองจิจูด โปรดทราบว่าข้อมูลเขตเวลาอาจไม่พร้อมใช้งานสำหรับสถานที่ที่อยู่เหนือน้ำ เช่น มหาสมุทรหรือทะเล

คำขอเขตเวลาจะอยู่ในรูปแบบต่อไปนี้

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

โดยที่ outputFormat อาจเป็นค่าใดค่าหนึ่งต่อไปนี้

  • json (แนะนำ) ซึ่งระบุเอาต์พุตใน JavaScript Object Notation (JSON) หรือ
  • xml ระบุเอาต์พุตใน XML ซึ่งรวมอยู่ในโหนด <TimeZoneResponse>

พารามิเตอร์ที่จำเป็น

สถานที่

ทูเพิลละติจูดและลองจิจูดที่คั่นด้วยคอมมา location=39.6034810,-119.6822510 ซึ่งแสดงตำแหน่งที่จะค้นหา

การประทับเวลา

เวลาที่ต้องการเป็นวินาทีนับตั้งแต่เที่ยงคืนของวันที่ 1 มกราคม 1970 ตามเวลา UTC Time Zone API ใช้ timestamp เพื่อพิจารณาว่าควรใช้เวลาออมแสงหรือไม่ โดยอิงตามเขตเวลาของ location

โปรดทราบว่า API ไม่ได้พิจารณาเขตเวลาที่ผ่านมา กล่าวคือ หากคุณระบุการประทับเวลาในอดีต API จะไม่พิจารณาความเป็นไปได้ที่สถานที่ตั้งนั้นเคยอยู่ในเขตเวลาอื่น

พารามิเตอร์ที่ไม่บังคับ

ภาษา

ภาษาที่จะแสดงผลลัพธ์

  • ดูรายการภาษาที่รองรับ Google อัปเดตภาษาที่รองรับอยู่บ่อยครั้ง รายการนี้จึงอาจไม่ครอบคลุมทั้งหมด
  • หากไม่ได้ระบุ language ไว้ API จะพยายามใช้ภาษาที่ต้องการตามที่ระบุไว้ในส่วนหัว Accept-Language
  • API จะพยายามอย่างเต็มที่เพื่อให้ที่อยู่ที่อ่านง่ายสำหรับทั้งผู้ใช้และคนในพื้นที่ เพื่อให้บรรลุเป้าหมายดังกล่าว ระบบจะแสดงที่อยู่ในภาษาท้องถิ่น โดยแปลงเป็นสคริปต์ที่ผู้ใช้อ่านได้หากจำเป็น ตามภาษาที่ต้องการ ส่วนที่อยู่อื่นๆ จะแสดงในภาษาที่ต้องการ คอมโพเนนต์ของที่อยู่ ทั้งหมดจะแสดงในภาษาเดียวกัน ซึ่งเลือกจากคอมโพเนนต์แรก
  • หากชื่อไม่มีในภาษาที่ต้องการ API จะใช้ชื่อที่ใกล้เคียงที่สุด
  • ภาษาที่ต้องการมีอิทธิพลเล็กน้อยต่อชุดผลลัพธ์ที่ API เลือกแสดงผลและลำดับการแสดงผล โปรแกรมเข้ารหัสพิกัดภูมิศาสตร์จะตีความตัวย่อแตกต่างกันไปตามภาษา เช่น ตัวย่อของประเภทถนน หรือคำพ้องความหมายที่อาจใช้ได้ในภาษาหนึ่งแต่ใช้ไม่ได้ในอีกภาษาหนึ่ง เช่น utca และ tér เป็นคำพ้องความหมายของคำว่าถนนในภาษาฮังการี

ตัวอย่างเขตเวลา

ส่วนนี้ประกอบด้วยตัวอย่างการค้นหาที่แสดงให้เห็นฟีเจอร์ของ API

คำค้นหาด้านล่างจะส่งคำขอเขตเวลาสำหรับรัฐเนวาดา สหรัฐอเมริกา การประทับเวลาตั้งค่าเป็นวันที่ 5 ธันวาคม 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>

คำค้นหาด้านล่างจะส่งคำขอเขตเวลาสำหรับรัฐเนวาดา สหรัฐอเมริกา ตำแหน่งจะเหมือนกับคำขอด้านบน แต่การประทับเวลาตั้งค่าเป็นวันที่ 15 มีนาคม 2024 ตอนนี้การตอบกลับจะมีออฟเซ็ตเวลาออมแสงด้วย

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>

ตัวอย่างนี้คล้ายกับ 2 ตัวอย่างข้างต้น แต่จะตั้งค่าพารามิเตอร์ภาษา ตอนนี้คำตอบจะได้รับการแปลเป็นภาษาสเปน

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>

คำตอบเกี่ยวกับเขตเวลา

สำหรับคำขอที่ถูกต้องแต่ละรายการ เขตเวลาจะแสดงผลการตอบกลับในรูปแบบที่ระบุไว้ใน URL คำขอ

TimeZoneResponse

ช่อง ต้องระบุ ประเภท คำอธิบาย
ต้องระบุ TimeZoneStatus ดูข้อมูลเพิ่มเติมได้ที่ TimeZoneStatus
ไม่บังคับ ตัวเลข

ค่าออฟเซ็ตสำหรับเวลาออมแสงเป็นวินาที ค่านี้จะเป็น 0 หากเขตเวลาไม่ได้อยู่ในเวลาออมแสงในช่วง timestamp ที่ระบุ

ไม่บังคับ สตริง

ข้อมูลโดยละเอียดเกี่ยวกับสาเหตุที่อยู่เบื้องหลังรหัสสถานะที่ระบุ รวมไว้หากสถานะไม่ใช่ Ok

ไม่บังคับ ตัวเลข

ค่าออฟเซ็ตจาก UTC (เป็นวินาที) สำหรับสถานที่ตั้งที่ระบุ การดำเนินการนี้ไม่ส่งผลต่อเวลาออมแสง

ไม่บังคับ สตริง

สตริงที่มีรหัสของเขตเวลา เช่น "America/Los_Angeles" หรือ "Australia/Sydney" รหัสเหล่านี้กำหนดโดยโปรเจ็กต์ Unicode Common Locale Data Repository (CLDR) และปัจจุบันมีอยู่ในไฟล์ timezone.xml เมื่อเขตเวลามีรหัสหลายรหัส ระบบจะแสดงผลรหัส Canonical ในการตอบกลับ XML ค่านี้จะเป็นชื่อแทนแรกของแต่ละเขตเวลา เช่น ระบบจะแสดงผล "Asia/Calcutta" ไม่ใช่ "Asia/Kolkata"

ไม่บังคับ สตริง

ชื่อแบบยาวของเขตเวลา ระบบจะแปลช่องนี้หากมีการตั้งค่าพารามิเตอร์ภาษา เช่น Pacific Daylight Time หรือ Australian Eastern Daylight Time

TimeZoneStatus

ฟิลด์ status ภายในออบเจ็กต์การตอบกลับเขตเวลาจะมีสถานะของคำขอ ช่อง status อาจมีค่าต่อไปนี้

  • OK หมายความว่าคําขอเสร็จสมบูรณ์แล้ว

  • INVALID_REQUEST บ่งชี้ว่าคำขอมีรูปแบบไม่ถูกต้อง

  • OVER_DAILY_LIMIT บ่งบอกถึงสิ่งต่อไปนี้

    • ไม่มีคีย์ API หรือคีย์ API ไม่ถูกต้อง
    • ยังไม่ได้เปิดใช้การเรียกเก็บเงินในบัญชีของคุณ
    • เกินขีดจำกัดการใช้งานที่กำหนดเอง
    • วิธีการชำระเงินที่ระบุใช้ไม่ได้อีกต่อไป (เช่น บัตรเครดิตหมดอายุ)

  • OVER_QUERY_LIMIT บ่งชี้ว่าผู้ส่งคำขอใช้เกินโควต้า

  • REQUEST_DENIED บ่งชี้ว่า API ไม่ได้ดำเนินการตามคำขอจนเสร็จสมบูรณ์ ยืนยันว่าได้ส่งคำขอผ่าน HTTPS แทน HTTP

  • UNKNOWN_ERROR บ่งบอกถึงข้อผิดพลาดที่ไม่รู้จัก

  • ZERO_RESULTS บ่งชี้ว่าไม่พบข้อมูลเขตเวลาสำหรับตำแหน่งหรือเวลาที่ระบุ ตรวจสอบว่าคำขอเป็นสถานที่บนบก ไม่ใช่น้ำ

กำลังคำนวณเวลาท้องถิ่น

เวลาท้องถิ่นของสถานที่ตั้งที่ระบุคือผลรวมของพารามิเตอร์ timestamp และช่อง dstOffset และ rawOffset จากผลลัพธ์