시간대 요청 및 응답

시간대

Time Zone API 요청은 URL 문자열로 구성됩니다. API는 위도/경도 쌍으로 지정된 지구상의 한 지점에 대한 시간대 데이터를 반환합니다. 해양과 같은 수역에 있는 위치의 경우 시간대 데이터를 사용할 수 없을 수 있습니다.

시간대 요청은 다음 형식을 취합니다.

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

여기서 outputFormat은 다음 값 중 하나일 수 있습니다.

json (권장)은 JavaScript 객체 표기법 (JSON)의 출력을 나타냅니다.
xml는 <TimeZoneResponse> 노드 내에 래핑된 XML의 출력을 나타냅니다.

참고: URL이 유효하려면 올바르게 인코딩되어야 하며 모든 웹 서비스에서 16384자로 제한됩니다. URL을 구성할 때 이 제한에 유의하세요. 브라우저, 프록시, 서버마다 URL 문자 제한이 다를 수도 있습니다.

필수 매개변수

위치

쉼표로 구분된 위도, 경도 튜플(location=39.6034810,-119.6822510)로, 조회할 위치를 나타냅니다.
타임스탬프

원하는 시간(1970년 1월 1일 자정(UTC) 이후 경과된 시간(초))입니다. Time Zone API는 timestamp를 사용하여 location의 시간대에 따라 일광 절약 시간을 적용해야 하는지 여부를 확인합니다.

API는 이전 시간대를 고려하지 않습니다. 즉, 과거 타임스탬프를 지정하면 API는 위치가 이전에 다른 시간대에 있었을 가능성을 고려하지 않습니다.

선택적 매개변수

language

결과를 반환할 언어입니다.
- 지원되는 언어 목록을 참고하세요. Google에서는 지원되는 언어를 자주 업데이트하므로 이 목록에 모든 언어가 포함되지 않을 수도 있습니다.
- language가 제공되지 않으면 API는 Accept-Language 헤더에 지정된 기본 언어를 사용하려고 시도합니다.
- API는 사용자와 현지인 모두가 읽을 수 있는 상세 주소를 제공하기 위해 최선을 다합니다. 이 목표를 달성하기 위해 선호하는 언어를 준수하여 필요한 경우 사용자가 읽을 수 있는 스크립트로 음역된 현지 언어의 거리 주소를 반환합니다. 다른 모든 주소는 기본 언어로 반환됩니다. 주소 구성요소는 모두 첫 번째 구성요소에서 선택한 동일한 언어로 반환됩니다.
- 선호하는 언어로 이름을 사용할 수 없는 경우 API는 가장 일치하는 이름을 사용합니다.
- 기본 언어는 API가 반환하도록 선택한 결과 집합과 반환되는 순서에 약간의 영향을 미칩니다. 지오코더는 언어에 따라 약어를 다르게 해석합니다. 예를 들어 거리 유형의 약어나 한 언어에서는 유효하지만 다른 언어에서는 유효하지 않은 동의어가 있습니다. 예를 들어 utca와 tér은 헝가리어로 거리의 동의어입니다.

시간대 예

이 섹션에는 API의 기능을 보여주는 샘플 쿼리가 포함되어 있습니다.

아래 쿼리는 미국 네바다에 대해 시간대 요청을 수행합니다. 타임스탬프는 2024년 12월 5일로 설정됩니다.

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>

아래 쿼리는 미국 네바다에 대해 시간대 요청을 수행합니다. 위 요청과 위치는 동일하지만 타임스탬프가 2024년 3월 15일로 설정되어 있습니다. 이제 응답에 일광 절약 시간 오프셋이 포함됩니다.

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>

이 예시는 위의 두 예제와 비슷하지만 언어 매개변수를 설정합니다. 이제 응답이 스페인어로 현지화됩니다.

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>

시간대 응답

각 유효한 요청에 대해 시간대는 요청 URL 내에 표시된 형식으로 응답을 반환합니다.

TimeZoneResponse

필드	필수	유형	설명
`status`	required	TimeZoneStatus	자세한 내용은 TimeZoneStatus를 참고하세요.
`dstOffset`	선택사항	숫자	일광 절약 시간의 오프셋(초)입니다. 지정된 `timestamp` 동안 시간대가 일광 절약 시간대에 있지 않으면 0입니다.
`errorMessage`	선택사항	문자열	지정된 상태 코드의 이유에 관한 자세한 정보입니다. 상태가 `Ok`이 아닌 경우 포함됩니다.
`rawOffset`	선택사항	숫자	지정된 위치의 UTC 오프셋 (초)입니다. 여기에는 일광 절약 시간이 적용되지 않습니다.
`timeZoneId`	선택사항	문자열	'America/Los_Angeles' 또는 'Australia/Sydney'와 같은 시간대의 ID가 포함된 문자열 이러한 ID는 유니코드 Common Locale Data Repository (CLDR) 프로젝트에 의해 정의되며 현재 timezone.xml 파일에서 사용할 수 있습니다. 시간대에 ID가 여러 개 있는 경우 표준 ID가 반환됩니다. XML 응답에서 이는 각 시간대의 첫 번째 별칭입니다. 예를 들어 'Asia/Kolkata'가 아닌 'Asia/Calcutta'가 반환됩니다.
`timeZoneName`	선택사항	문자열	시간대의 긴 형식 이름입니다. 언어 매개변수가 설정된 경우 이 필드는 현지화됩니다. 예: `Pacific Daylight Time` 또는 `Australian Eastern Daylight Time`.

TimeZoneStatus

시간대 응답 객체 내의 status 필드에는 요청의 상태가 포함됩니다. status 필드는 다음 값을 포함할 수 있습니다.

OK는 요청이 성공했음을 나타냅니다.
INVALID_REQUEST는 요청의 형식이 잘못되었음을 나타냅니다.
OVER_DAILY_LIMIT는 다음 중 하나를 나타냅니다.
- API 키가 누락되었거나 잘못되었습니다.
- 계정에 결제가 사용 설정되어 있지 않습니다.
- 자체 적용되는 사용량 한도를 초과했습니다.
- 제공된 결제 수단이 더 이상 유효하지 않습니다 (예: 신용카드가 만료됨).
OVER_QUERY_LIMIT는 요청자가 할당량을 초과했음을 나타냅니다.
REQUEST_DENIED는 API가 요청을 완료하지 않았음을 나타냅니다. HTTP 대신 HTTPS를 통해 요청이 전송되었는지 확인합니다.
UNKNOWN_ERROR은 알 수 없는 오류를 나타냅니다.
ZERO_RESULTS는 지정된 위치 또는 시간에 대한 시간대 데이터를 찾을 수 없음을 나타냅니다. 요청이 육상 위치에 대한 것이며 해상 위치에 대한 것이 아님을 확인합니다.

현지 시간 계산

특정 위치의 현지 시간은 timestamp 매개변수와 결과의 dstOffset 및 rawOffset 필드의 합계입니다.

시간대 요청 및 응답

시간대

필수 매개변수

위치

타임스탬프

선택적 매개변수

language

시간대 예

URL

curl

JSON

XML

URL

curl

JSON

XML

URL

curl

JSON

XML

시간대 응답

TimeZoneResponse

`status`

`dstOffset`

`errorMessage`

`rawOffset`

`timeZoneId`

`timeZoneName`

TimeZoneStatus

현지 시간 계산

시간대 요청 및 응답 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

시간대

필수 매개변수

위치

타임스탬프

선택적 매개변수

language

시간대 예

URL

curl

JSON

XML

URL

curl

JSON

XML

URL

curl

JSON

XML

시간대 응답

TimeZoneResponse

status

dstOffset

errorMessage

rawOffset

timeZoneId

timeZoneName

TimeZoneStatus

현지 시간 계산

시간대 요청 및 응답

`status`

`dstOffset`

`errorMessage`

`rawOffset`

`timeZoneId`

`timeZoneName`