Все готово!

Прежде чем приступить к разработке, ознакомьтесь с документацией для разработчиков.

Активировать Google Maps Time Zone API

Чтобы помочь вам освоиться, мы покажем, как выполнить некоторые необходимые действия в консоли разработчика Google:

  1. Создание или выбор проекта
  2. Активировать Google Maps Time Zone API
  3. Создание соответствующих ключей

Руководство для разработчиков

Google Maps Time Zone API обеспечивает простой интерфейс для запроса сведений о часовом поясе для какого-либо местоположения на Земле, а также о разнице во времени относительно UTC для этого местоположения.

Эта служба также доступна в Java Client, Python Client, Go Client и Node.js Client for Google Maps Services.

Этот документ предназначен для разработчиков веб-сайтов и мобильных приложений, которым требуется использовать в картах данные о времени, предоставляемые одним из интерфейсов Google Maps API. Документ содержит основные сведения по использованию API и справочные материалы по доступным параметрам.

Введение

Google Maps Time Zone API предоставляет данные о смещении времени для различных местоположений на земной поверхности. Вы запрашиваете сведения о часовом поясе для определенной пары значений широты и долготы, а также для даты. API возвращает название этого часового пояса, смещение времени относительно UTC и смещение при переходе на летнее время.

Доступ к Google Maps Time Zone API выполняется по протоколу HTTPS.

Перед началом разработки с использованием Time Zone API проверьте требования аутентификации (необходим ключ API) и лимиты использования API.

Запросы часового пояса

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

Запрос Google Maps Time Zone API имеет следующий вид:

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

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

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

Внимание! Для отправки запроса следует использовать протокол HTTPS, а не HTTP.

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

Параметры запроса

Все параметры разделяются амперсандами (&) в соответствии со стандартом URL-адресов. Список параметров и их возможные значения приведены ниже.

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

  • location – кортеж значений широты и долготы, разделенных запятой (например, location=-33.86,151.20), представляющих местоположение, которое необходимо найти.
  • timestamp определяет желаемое время в секундах с полночи 1 января 1970 года по UTC. Интерфейс Google Maps Time Zone API использует timestamp, чтобы определить, требуется ли применять летнее время. Данные о времени до 1970 г. могут выражаться в виде отрицательных значений.
  • key – ключ API вашего приложения. Этот ключ используется для идентификации приложения в целях управления квотами. См. дополнительную информацию о получении ключа.

    Примечание. Пользователи Google Maps APIs Premium Plan в запросах Служба Time Zone могут использовать либо ключ API, либо действительный идентификатор клиента и цифровую подпись. См. дополнительную информацию о параметрах аутентификации пользователей Premium Plan.

Дополнительные параметры

  • language – язык, на котором выводятся результаты. См. список поддерживаемых языков домена. Обратите внимание, что список языков постоянно пополняется, поэтому он может быть неполным. По умолчанию используется параметр en (английский язык).

Ответы на запросы часового пояса

Для каждого допустимого запроса служба часовых поясов вернет ответ в формате, указанном в URL-адресе запроса. В каждом ответе будут содержаться следующие элементы.

  • dstOffset: смещение для перехода на летнее время, выраженное в секундах. Это значение будет равно 0, если для часового пояса не используется переход на летнее время в период, указанный параметром timestamp.
  • rawOffset: смещение от UTC (в секундах) для данного местоположения. При этом не учитывается переход на летнее время.
  • timeZoneId: строка, содержащая идентификатор "tz" часового пояса, например, "America/Los_Angeles" или "Australia/Sydney". Эти идентификаторы указаны в Базе данных часовых поясов IANA, которая также имеется в доступном для поиска формате в Списке часовых поясов базы данных tz в Википедии.
  • timeZoneName: строка, содержащая полное название часового пояса. Это поле будет локализовано, если установлен соответствующий параметр для языка, например: "Pacific Daylight Time" или "Australian Eastern Daylight Time".
  • status: строка, указывающая статус ответа.
    • OK – указывает, что запрос выполнен успешно.
    • INVALID_REQUEST – указывает, что запрос содержит ошибки.
    • OVER_QUERY_LIMIT – указывает, что пользователь, выполняющий запрос, превысил квоту.
    • REQUEST_DENIED – указывает, что API не выполнил запрос. Убедитесь, что запрос был отправлен с использованием протокола HTTPS, а не HTTP.
    • UNKNOWN_ERROR – указывает, что возникла неизвестная ошибка.
    • ZERO_RESULTS – указывает, что для этого положения или времени не удалось найти данные о часовом поясе. Убедитесь, что в запросе указано местоположение на суше, а не на воде.
  • error_message: более подробная информация о причинах получения указанного кода состояния, если он отличается от OK.

    Примечание. В ответе может и не быть этого поля, а содержимое самого поля может быть другим.

Вычисление местного времени

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

Примеры запроса

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

В приведенном ниже примере представлен запрос часового пояса для штата Невада, США. Для метки времени указана дата 8 марта 2012 г.

JSON

Запрос:

https://maps.googleapis.com/maps/api/timezone/json?location=39.6034810,-119.6822510&timestamp=1331161200&key=YOUR_API_KEY

Ответ:

{
   "dstOffset" : 0,
   "rawOffset" : -28800,
   "status" : "OK",
   "timeZoneId" : "America/Los_Angeles",
   "timeZoneName" : "Pacific Standard Time"
}
    
XML

Запрос:

https://maps.googleapis.com/maps/api/timezone/xml?location=39.6034810,-119.6822510&timestamp=1331161200&key=YOUR_API_KEY

Ответ:

<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 марта 2012 г. Теперь ответ содержит смещение для перехода на летнее время.

JSON

Запрос:

https://maps.googleapis.com/maps/api/timezone/json?location=39.6034810,-119.6822510&timestamp=1331766000&key=YOUR_API_KEY

Ответ:

{
   "dstOffset" : 3600,
   "rawOffset" : -28800,
   "status" : "OK",
   "timeZoneId" : "America/Los_Angeles",
   "timeZoneName" : "Pacific Daylight Time"
}
    
XML

Запрос:

https://maps.googleapis.com/maps/api/timezone/xml?location=39.6034810,-119.6822510&timestamp=1331766000&key=YOUR_API_KEY

Ответ:

<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>

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

JSON

Запрос:

https://maps.googleapis.com/maps/api/timezone/json?location=39.6034810,-119.6822510&timestamp=1331766000&language=es&key=YOUR_API_KEY

Ответ:

{
   "dstOffset" : 3600,
   "rawOffset" : -28800,
   "status" : "OK",
   "timeZoneId" : "America/Los_Angeles",
   "timeZoneName" : "Hora de verano del Pacífico"
}
    
XML

Запрос:

https://maps.googleapis.com/maps/api/timezone/xml?location=39.6034810,-119.6822510&timestamp=1331766000&language=es&key=YOUR_API_KEY

Ответ:

<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>

Параметр sensor

Ранее запросы Google Maps API обязательно должны были содержать параметр sensor, чтобы указать, использовался ли приложением датчик для определения местоположения пользователя. Этот параметр больше не используется.

Оставить отзыв о...

Текущей странице
Google Maps Time Zone API
Google Maps Time Zone API
Нужна помощь? Обратитесь в службу поддержки.