Следите за использованием ключа, пока не упёрлись в лимит
Наблюдение за заголовками квоты по ходу работы показывает приближение к лимиту задолго до того, как запрос будет отклонён.
Определение часового пояса по любой широте и долготе
Сами по себе координаты не говорят, который час в точке на карте. Эндпоинт часовых поясов принимает широту и долготу и возвращает название часового пояса, его текущее смещение от UTC и аббревиатуру.
Выполнение запроса
GET /v1/timezone?lat=52.3676&lon=4.9041{
"status": "ok",
"timezone": "Europe/Amsterdam",
"utc_offset": "+02:00",
"abbreviation": "CEST"
}Поле timezone содержит стандартный идентификатор, который можно напрямую передать в большинство библиотек для работы с датой и временем. Поля utc_offset и abbreviation полезны для отображения, когда вы хотите показать читателю что-то более привычное, чем строка-идентификатор.
Второй пример, по ту сторону линии перемены дат
Смещения не всегда представляют собой небольшие круглые числа, а некоторые места находятся по другую сторону линии перемены дат от большей части населения мира.
GET /v1/timezone?lat=-17.7333&lon=168.3273{
"status": "ok",
"timezone": "Pacific/Efate",
"utc_offset": "+11:00",
"abbreviation": "VUT"
}Обрабатывайте возвращённый идентификатор одинаково, независимо от того, насколько он далёк от часов вашего сервера. Ваша библиотека для работы с датами уже умеет правильно обрабатывать смещение в одиннадцать часов, поэтому для мест, далёких от вашего часового пояса, не нужно писать никаких особых случаев.
Сочетание с геокодированием
Этому эндпоинту нужны только координаты, поэтому он естественно сочетается с прямым или обратным геокодированием. Сначала геокодируйте адрес, чтобы получить его широту и долготу, затем передайте их прямо в /v1/timezone и узнайте, в каком поясе находится это место, не спрашивая пользователя о часовых поясах напрямую.
Связанный короткий путь
Если у вас уже есть IP-адрес посетителя, а не геокодированный адрес, эндпоинт /v1/ip возвращает поле timezone прямо в своём ответе, вообще без отдельного вызова этого эндпоинта. Обращайтесь к /v1/timezone напрямую, когда у вас уже есть координаты без связанного определения IP, например адрес из профиля доставки клиента.
Учёт перехода на летнее время
Поля utc_offset и abbreviation отражают смещение, действующее на тот момент, о котором вы спросили. Если вас интересует конкретная дата, а не текущий момент, передайте метку времени unix в параметре time, чтобы ответ отражал смещение, действовавшее в ту дату, а не сегодняшнее.
GET /v1/timezone?lat=52.3676&lon=4.9041&time=1731000000Ошибка, которой стоит избегать
Вызвать этот эндпоинт один раз и надолго закешировать значение utc_offset это распространённый короткий путь, который дважды в год ломается в местах, где переходят на летнее время. Сам идентификатор часового пояса стабилен, и его безопасно кешировать. Смещение и аббревиатура нет, поскольку они меняются вместе с календарём, поэтому вычисляйте их заново в момент отображения, а не храните рядом с идентификатором.
Сколько это стоит
Каждое определение часового пояса это один запрос. Если вы уже геокодируете адрес в процессе регистрации или оформления заказа, добавление определения часового пояса для того же места удваивает число запросов в этом процессе, с одного до двух, что всё равно пустяк на фоне 2 500 бесплатных запросов в день, которые входят в каждый ключ.
В данных о часовых поясах легко ошибиться, если вести их вручную, особенно на границах перехода на летнее время, поэтому их стоит брать из единого источника, а не поддерживать собственную таблицу смещений. В документации по определению часового пояса приведён полный список параметров.