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

เขตเวลา

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

คำขอเขตเวลาจะมีรูปแบบดังนี้

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

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

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

หมายเหตุ: URL ต้องเข้ารหัสอย่างถูกต้อง จึงจะใช้งานได้ และมีความยาวไม่เกิน 16384 ตัวสำหรับเว็บเซอร์วิสทั้งหมด โปรดทราบขีดจำกัดนี้เมื่อสร้าง URL โปรดทราบว่าเบราว์เซอร์ พร็อกซี และเซิร์ฟเวอร์ต่างๆ อาจมีขีดจำกัดอักขระของ URL ที่แตกต่างกันด้วย

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

• สถานที่

  ค่าละติจูดและลองจิจูดที่คั่นด้วยคอมมา 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

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

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

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

<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 ตอนนี้การตอบกลับจะมีการชดเชยเวลาออมแสง

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

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

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

<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 ตัวอย่างด้านบน แต่ตั้งค่าพารามิเตอร์ภาษา ตอนนี้การตอบกลับจะเป็นภาษาสเปน

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

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'

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

<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

ช่อง 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 ช่องจากผลลัพธ์