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

Múi giờ

Yêu cầu Time Zone API được tạo dưới dạng một 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 về múi giờ có thể không có sẵn cho những 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 hai giá trị sau:

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

Lưu ý: URL phải được mã hoá đúng cách để hợp lệ và giới hạn ở 16384 ký tự cho tất cả các dịch vụ web. Hãy lưu ý đến giới hạn này khi tạo URL. Xin lưu ý rằng các trình duyệt, proxy và máy chủ khác nhau cũng có thể có giới hạn ký tự URL khác nhau.

Thông số bắt buộc

vị trí

Một bộ gồm vĩ độ,kinh độ được phân tách bằng dấu phẩy, location=39.6034810,-119.6822510, biểu thị vị trí cần tra cứu.
timestamp

Thời gian mong muốn tính bằng giây kể từ nửa đêm ngày 1 tháng 1 năm 1970 theo giờ UTC. Time Zone API sử dụng timestamp để xác định xem có nên áp dụng Giờ tiết kiệm ánh sáng ban ngày 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 các múi giờ trong quá khứ. Tức là nếu bạn chỉ định một dấu thời gian trong quá khứ, API sẽ không tính đến khả năng vị trí đó trước đây ở một múi giờ khác.

Thông số tùy chọn

language

Ngôn ngữ mà bạn muốn nhận kết quả.
- Xem danh sách các 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ể chưa đầy đủ.
- Nếu bạn không cung cấp language, 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 cung cấp một đị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 đó, phương thức này sẽ trả về địa chỉ đường phố bằng ngôn ngữ địa phương, được chuyển tự sang một kịch bản mà người dùng có thể đọc được (nếu cần), tuân theo ngôn ngữ ưu tiên. Tất cả các địa chỉ khác đều được trả về bằng ngôn ngữ ưu tiên. Tất cả cá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 kết quả trùng khớp gần nhất.
- Ngôn ngữ ưu tiên có ảnh hưởng nhỏ đến tập hợp kết quả mà API chọn trả về và thứ tự trả về. Trình 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à từ đồng nghĩa với đường phố 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 bên dưới thực hiện một yêu cầu về 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%2C-119.6822510
  ×tamp=1733428634
  &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/timezone/json?location=39.6034810%2C-119.6822510×tamp=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 bên dưới thực hiện một yêu cầu về múi giờ cho Nevada, Hoa Kỳ. Vị trí này giống với 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. Phản hồi hiện bao gồm độ lệch Giờ mùa hè.

URL

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

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/timezone/json?location=39.6034810%2C-119.6822510×tamp=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 một tham số ngôn ngữ. Giờ đây, câu trả lời 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%2C-119.6822510
  ×tamp=1710547034
  &key=YOUR_API_KEY

curl

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'

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ệ, Time Zone sẽ trả về một phản hồi ở đị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 phải là Giờ tiết kiệm ánh sáng ban ngày 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ác `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) của vị trí đã cho. Thời gian này không tính đế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 của Unicode (CLDR) và hiện có trong tệp timezone.xml. Khi một múi giờ có nhiều mã nhận dạng, mã nhận dạng chuẩn sẽ được trả về. Trong các 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 bạn đặt tham số ngôn ngữ. 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 yêu cầu đã thành công.
INVALID_REQUEST cho biết yêu cầu không đúng định dạng.
OVER_DAILY_LIMIT cho biết một trong những trường hợp sau:
- Khoá API bị thiếu hoặc không hợp lệ.
- Bạn chưa bật tính năng thanh toán cho tài khoản của mình.
- Bạn đã vượt quá hạn mức sử dụng do chính mình đặt ra.
- Phương thức thanh toán bạn 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 đã xảy ra lỗi không xác định.
ZERO_RESULTS cho biết không tìm thấy dữ liệu múi giờ cho vị trí hoặc thời gian đã 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.

Tính toán 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 và 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ờ

Thông 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

Tính toán 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ờ

Thông 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

Tính toán giờ địa phương

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

`status`

`dstOffset`

`errorMessage`

`rawOffset`

`timeZoneId`

`timeZoneName`