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

เขตเวลา

คำขอ 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 เลือกที่จะแสดงผล และลำดับที่แสดงผล Geocoder จะตีความตัวย่อแตกต่างกันไปตามภาษา เช่น ตัวย่อสำหรับประเภทถนน หรือคำพ้องความหมายที่อาจ ใช้ได้ในภาษาหนึ่งแต่ใช้ไม่ได้ในอีกภาษาหนึ่ง เช่น utca และ tér เป็นคำพ้องความหมายของถนนในภาษาฮังการี

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

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

คำค้นหาด้านล่างจะส่งคำขอเขตเวลาสำหรับเนวาดา สหรัฐอเมริกา โดยการประทับเวลา จะตั้งค่าเป็นวันที่ 5 ธันวาคม 2024

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

curl -L -X GET 'https://maps.googleapis.com/maps/api/timezone/json?location=39.6034810%2C-119.6822510×tamp=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%2C-119.6822510
  ×tamp=1710547034
  &key=YOUR_API_KEY

curl -L -X GET 'https://maps.googleapis.com/maps/api/timezone/json?location=39.6034810%2C-119.6822510×tamp=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%2C-119.6822510
  ×tamp=1710547034
  &key=YOUR_API_KEY

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'

{
  "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 ขาดหายไปหรือไม่ถูกต้อง
  • บัญชีของคุณไม่ได้เปิดใช้การเรียกเก็บเงิน
  • มีการใช้งานเกินขีดจำกัดการใช้งานที่กำหนดเอง
  • วิธีการชำระเงินที่ระบุใช้ไม่ได้อีกต่อไป (เช่น บัตรเครดิตหมดอายุ)

• OVER_QUERY_LIMIT แสดงว่าผู้ขอใช้โควต้าเกินแล้ว

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

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

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

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

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