Google sử dụng công nghệ AI để dịch nội dung sang ngôn ngữ bạn ưu tiên. Bản dịch bằng AI có thể có lỗi.

Yêu cầu và phản hồi về múi giờ

Múi giờ

Yêu cầu API Múi giờ được tạo dưới dạng chuỗi URL. API này trả về dữ liệu múi giờ cho một điểm trên Trái Đất, được chỉ định bằng một cặp vĩ độ-kinh độ. Xin lưu ý rằng dữ liệu múi giờ có thể không có sẵn cho các vị trí trên mặt nước, chẳng hạn như đại dương hoặc biển.

Yêu cầu về Múi giờ có dạng như sau:

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

trong đó outputFormat có thể là một trong các giá trị sau:

json (nên dùng), cho biết kết quả ở định dạng JavaScript Object Notation (JSON); hoặc
xml, cho biết kết quả đầu ra ở định dạng XML, được gói trong một nút <TimeZoneResponse>.

Tham số bắt buộc

vị trí

Một bộ dữ liệu vĩ độ,kinh độ được phân tách bằng dấu phẩy, location=39.6034810,-119.6822510, đại diện cho vị trí cần tra cứu.

timestamp

Thời gian dự kiến tính bằng giây kể từ nửa đêm ngày 1 tháng 1 năm 1970 theo giờ UTC. API Múi giờ sử dụng timestamp để xác định xem có nên áp dụng Giờ mùa hè hay không, dựa trên múi giờ của location.

Xin lưu ý rằng API này không tính đến múi giờ trong quá khứ. Tức là nếu bạn chỉ định dấu thời gian trong quá khứ, API sẽ không tính đến khả năng vị trí đó trước đây nằm trong một múi giờ khác.

Thông số tùy chọn

language

Ngôn ngữ để trả về kết quả.

Xem danh sách ngôn ngữ được hỗ trợ. Google thường xuyên cập nhật các ngôn ngữ được hỗ trợ, vì vậy, danh sách này có thể không đầy đủ.
Nếu bạn không cung cấp language, thì API sẽ cố gắng sử dụng ngôn ngữ ưu tiên như được chỉ định trong tiêu đề Accept-Language.
API này cố gắng hết sức để cung cấp địa chỉ đường phố mà cả người dùng và người dân địa phương đều có thể đọc được. Để đạt được mục tiêu đó, API này sẽ trả về địa chỉ đường phố bằng ngôn ngữ địa phương, được chuyển tự sang một hệ chữ viết mà người dùng có thể đọc được nếu cần, đồng thời tuân thủ ngôn ngữ ưu tiên. Tất cả các địa chỉ khác được trả về bằng ngôn ngữ ưu tiên. Tất cả thành phần địa chỉ đều được trả về bằng cùng một ngôn ngữ, được chọn từ thành phần đầu tiên.
Nếu không có tên bằng ngôn ngữ ưu tiên, API sẽ sử dụng tên phù hợp nhất.
Ngôn ngữ ưu tiên có ảnh hưởng nhỏ đến nhóm kết quả mà API chọn trả về và thứ tự trả về. Bộ mã hoá địa lý diễn giải các từ viết tắt theo nhiều cách tuỳ thuộc vào ngôn ngữ, chẳng hạn như từ viết tắt cho các loại đường phố hoặc từ đồng nghĩa có thể hợp lệ trong một ngôn ngữ nhưng không hợp lệ trong ngôn ngữ khác. Ví dụ: utca và tér là các từ đồng nghĩa với "đường" trong tiếng Hungary.

Ví dụ về múi giờ

Phần này bao gồm một số truy vấn mẫu minh hoạ các tính năng của API.

Truy vấn dưới đây thực hiện yêu cầu múi giờ cho Nevada, Hoa Kỳ. Dấu thời gian được đặt thành ngày 5 tháng 12 năm 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>

Truy vấn dưới đây thực hiện yêu cầu múi giờ cho Nevada, Hoa Kỳ. Vị trí giống như yêu cầu ở trên, nhưng dấu thời gian được đặt thành ngày 15 tháng 3 năm 2024. Giờ đây, phản hồi sẽ bao gồm cả độ lệch giờ mùa hè.

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>

Ví dụ này tương tự như hai ví dụ trên, nhưng đặt tham số ngôn ngữ. Câu trả lời giờ đây sẽ được bản địa hoá sang tiếng Tây Ban Nha.

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>

Phản hồi về múi giờ

Đối với mỗi yêu cầu hợp lệ, Múi giờ sẽ trả về một phản hồi theo định dạng được chỉ định trong URL yêu cầu.

TimeZoneResponse

Trường	Bắt buộc	Loại	Mô tả
`status`	bắt buộc	TimeZoneStatus	Hãy xem TimeZoneStatus để biết thêm thông tin.
`dstOffset`	tùy chọn	số	Thời gian chênh lệch cho giờ mùa hè tính bằng giây. Giá trị này sẽ bằng 0 nếu múi giờ không nằm trong Giờ mùa hè trong `timestamp` được chỉ định.
`errorMessage`	tùy chọn	chuỗi	Thông tin chi tiết về lý do dẫn đến mã trạng thái đã cho. Được đưa vào nếu trạng thái không phải là `Ok`.
`rawOffset`	tùy chọn	số	Thời gian chênh lệch so với giờ UTC (tính bằng giây) cho vị trí đã cho. Điều này không ảnh hưởng đến giờ mùa hè.
`timeZoneId`	tùy chọn	chuỗi	một chuỗi chứa mã nhận dạng của múi giờ, chẳng hạn như "America/Los_Angeles" hoặc "Australia/Sydney". Các mã nhận dạng này được xác định theo dự án Kho lưu trữ dữ liệu ngôn ngữ chung (CLDR) của Unicode và hiện có trong tệp timezone.xml. Khi một múi giờ có nhiều mã nhận dạng, mã chuẩn sẽ được trả về. Trong phản hồi xml, đây là bí danh đầu tiên của mỗi múi giờ. Ví dụ: "Asia/Calcutta" được trả về, chứ không phải "Asia/Kolkata".
`timeZoneName`	tùy chọn	chuỗi	Tên đầy đủ của múi giờ. Trường này sẽ được bản địa hoá nếu tham số ngôn ngữ được đặt. Ví dụ: `Pacific Daylight Time` hoặc `Australian Eastern Daylight Time`.

TimeZoneStatus

Trường status trong đối tượng phản hồi Múi giờ chứa trạng thái của yêu cầu. Trường status có thể chứa các giá trị sau:

OK cho biết rằng yêu cầu đã thành công.
INVALID_REQUEST cho biết yêu cầu có định dạng không chính xác.
OVER_DAILY_LIMIT cho biết bất kỳ điều nào sau đây:
- Khoá API bị thiếu hoặc không hợp lệ.
- Tài khoản của bạn chưa được bật tính năng thanh toán.
- Đã vượt quá hạn mức sử dụng do bạn tự đặt.
- Phương thức thanh toán được cung cấp không còn hợp lệ (ví dụ: thẻ tín dụng đã hết hạn).
OVER_QUERY_LIMIT cho biết người yêu cầu đã vượt quá hạn mức.
REQUEST_DENIED cho biết API không hoàn tất yêu cầu. Xác nhận rằng yêu cầu đã được gửi qua HTTPS thay vì HTTP.
UNKNOWN_ERROR cho biết lỗi không xác định.
ZERO_RESULTS cho biết không tìm thấy dữ liệu múi giờ nào cho vị trí hoặc thời gian được chỉ định. Xác nhận rằng yêu cầu là cho một vị trí trên đất liền chứ không phải trên mặt nước.

Đang tính giờ địa phương

Giờ địa phương của một vị trí nhất định là tổng của tham số timestamp, cũng như các trường dstOffset và rawOffset trong kết quả.

Yêu cầu và phản hồi về múi giờ

Múi giờ

Tham số bắt buộc

vị trí

timestamp

Thông số tùy chọn

language

Ví dụ về múi giờ

URL

curl

JSON

XML

URL

curl

JSON

XML

URL

curl

JSON

XML

Phản hồi về múi giờ

TimeZoneResponse

`status`

`dstOffset`

`errorMessage`

`rawOffset`

`timeZoneId`

`timeZoneName`

TimeZoneStatus

Đang tính giờ địa phương

Yêu cầu và phản hồi về múi giờ Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.

Múi giờ

Tham số bắt buộc

vị trí

timestamp

Thông số tùy chọn

language

Ví dụ về múi giờ

URL

curl

JSON

XML

URL

curl

JSON

XML

URL

curl

JSON

XML

Phản hồi về múi giờ

TimeZoneResponse

status

dstOffset

errorMessage

rawOffset

timeZoneId

timeZoneName

TimeZoneStatus

Đang tính giờ địa phương

Yêu cầu và phản hồi về múi giờ

`status`

`dstOffset`

`errorMessage`

`rawOffset`

`timeZoneId`

`timeZoneName`