Запросы и ответы, связанные с часовыми поясами

Часовой пояс

Запросы к Time Zone API создаются в виде строки URL. API возвращает данные о часовом поясе для точки на земной поверхности, заданной парой значений широты и долготы. Обратите внимание, что данные о часовых поясах могут быть недоступны для местоположений над водой, например над океанами или морями.

Запрос часового пояса имеет следующий вид:

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

где outputFormat может принимать одно из следующих значений:

• json (рекомендуется) – вывод в формате JavaScript Object Notation (JSON);
• xml – указывает, что выходные данные должны быть в формате XML и заключены в узел <TimeZoneResponse>.

Примечание. URL должны быть правильно закодированы, чтобы быть действительными. Для всех веб-сервисов длина URL ограничена 16 384 символами. Учитывайте это ограничение при создании URL. Обратите внимание, что в разных браузерах, прокси-серверах и серверах могут действовать разные ограничения на количество символов в URL.

Обязательные параметры

• местоположение

  Кортеж широты и долготы,разделенных запятой, location=39.6034810,-119.6822510, представляющий местоположение для поиска.

• временная метка

  Время в секундах с полуночи 1 января 1970 г. по UTC. API часового пояса использует директиву timestamp, чтобы определить, нужно ли применять переход на летнее время, на основе часового пояса, указанного в директиве location.

  Обратите внимание, что API не учитывает исторические часовые пояса. То есть если вы укажете временную метку в прошлом, API не будет учитывать возможность того, что местоположение ранее находилось в другом часовом поясе.

Необязательные параметры

• language

  Язык, на котором будут возвращены результаты.

  • Вы можете ознакомиться со списком поддерживаемых языков. 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>

Этот пример аналогичен приведенным выше, но в нем также установлен параметр для языка. Ответ будет на испанском языке.

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 отсутствует или недействителен.
  • В вашем аккаунте не включены платежные функции.
  • Превышено заданное ограничение на использование.
  • Указанный способ оплаты больше не действует (например, истек срок действия кредитной карты).

• OVER_QUERY_LIMIT означает, что запрашивающее приложение превысило квоту.

• REQUEST_DENIED означает, что API не выполнил запрос. Убедитесь, что запрос был отправлен с использованием протокола HTTPS, а не HTTP.

• UNKNOWN_ERROR означает неизвестную ошибку.

• ZERO_RESULTS – для указанной позиции или времени не удалось найти данные о часовом поясе. Убедитесь, что запрос относится к местоположению на суше, а не на воде.

Как рассчитывается местное время

Местное время в определенном местоположении – это сумма параметра timestamp и полей dstOffset и rawOffset из результата.