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

Часовой пояс

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

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

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

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

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

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

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

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

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

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

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

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

language

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

  • Вы можете ознакомиться со списком поддерживаемых языков. Google часто обновляет список поддерживаемых языков, поэтому он может быть неполным.
  • Если параметр language не указан, API пытается использовать язык, заданный в заголовке Accept-Language.
  • API пытается предоставить почтовый адрес, который будет понятен как пользователю, так и местным жителям. Для этого он возвращает почтовые адреса на местном языке, при необходимости транслитерируя их в систему письма, понятную пользователю, с учетом предпочитаемого языка. Все остальные адреса возвращаются на предпочитаемом языке. Все компоненты адреса возвращаются на одном языке, который выбирается по первому компоненту.
  • Если название на выбранном языке недоступно, API использует наиболее близкое совпадение.
  • Предпочтительный язык немного влияет на набор результатов, возвращаемых API, и на порядок их возврата. Геокодер по-разному интерпретирует сокращения в зависимости от языка. Например, это касается сокращений для типов улиц или синонимов, которые могут быть допустимы в одном языке, но не в другом. Например, utca и tér – это синонимы слова "улица" на венгерском языке.

Примеры часовых поясов

Этот раздел содержит несколько примеров запроса, демонстрирующих возможности API-интерфейса.

В приведенном ниже примере представлен запрос часового пояса для штата Невада, США. Временная метка установлена на 5 декабря 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>

В приведенном ниже примере представлен запрос часового пояса для штата Невада, США. Местоположение такое же, как и в предыдущем запросе, но временная метка установлена на 15 марта 2024 года. Теперь ответ включает смещение летнего времени.

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>

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

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>

Ответы о часовых поясах

Для каждого допустимого запроса Time Zone API возвращает ответ в формате, указанном в URL запроса.

TimeZoneResponse

Поле Обязательно Тип Описание
Обязательно TimeZoneStatus Дополнительную информацию можно найти в описании TimeZoneStatus.
необязательно число

Смещение времени относительно летнего времени (в секундах). Если в часовом поясе не используется летнее время, значение будет равно нулю.timestamp

необязательно string

Подробная информация о причинах, по которым был присвоен код статуса. Включается, если статус отличается от Ok.

необязательно число

Смещение времени относительно UTC (в секундах) для указанного местоположения. Переход на летнее время не учитывается.

необязательно string

Строка, содержащая идентификатор часового пояса, например "America/Los_Angeles" или "Australia/Sydney". Эти идентификаторы определены в проекте Unicode Common Locale Data Repository (CLDR) и в настоящее время доступны в файле timezone.xml. Если у часового пояса несколько идентификаторов, возвращается канонический. В ответах XML это первый псевдоним каждого часового пояса. Например, возвращается "Asia/Calcutta", а не "Asia/Kolkata".

необязательно string

Полное название часового пояса. Если указано значение для параметра языка, возвращается локализованная фраза. Pacific Daylight Time или Australian Eastern Daylight Time.

TimeZoneStatus

Поле status в объекте ответа Time Zone содержит статус запроса. Поле status может содержать следующие значения:

  • OK указывает, что запрос был выполнен успешно.

  • INVALID_REQUEST указывает, что запрос был сформирован неправильно.

  • OVER_DAILY_LIMIT указывает на любое из следующего:

    • Ключ API отсутствует или недействителен.
    • В вашем аккаунте не включены платежные функции.
    • Превышено заданное ограничение на использование.
    • Указанный способ оплаты больше не действует (например, истек срок действия кредитной карты).

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

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

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

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

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

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