Следите за использованием ключа, пока не упёрлись в лимит
Наблюдение за заголовками квоты по ходу работы показывает приближение к лимиту задолго до того, как запрос будет отклонён.
Перевод отметки времени UTC в местное время ваших пользователей
Хранить метки времени в UTC правильно для базы данных. Показывать UTC пользователю в обращении в поддержку, подтверждении заказа или журнале активности неправильно, и это одно из самых распространённых мелких раздражителей в интерфейсе продукта.
Преобразование в два шага
Сначала определите, для какого места нужно интерпретировать метку времени: это могут быть координаты сохранённого адреса или координаты из поиска по IP. Затем передайте эти координаты и саму метку времени UTC в /v1/timezone через параметр time, чтобы возвращённое смещение соответствовало нужному моменту, а не текущему.
GET /v1/timezone?lat=40.7128&lon=-74.0060&time=1734000000{
"status": "ok",
"timezone": "America/New_York",
"utc_offset": "-05:00",
"abbreviation": "EST"
}Примените utc_offset к сохранённой метке времени UTC или передайте идентификатор часового пояса в свой код форматирования дат и показывайте результат вместо необработанного значения UTC.
Второй пример с разницей в несколько месяцев
Одни и те же координаты возвращают разное смещение в зависимости от переданной метки времени, и именно поэтому существует параметр time.
GET /v1/timezone?lat=40.7128&lon=-74.0060&time=1719000000{
"status": "ok",
"timezone": "America/New_York",
"utc_offset": "-04:00",
"abbreviation": "EDT"
}Обратите внимание: для одного и того же места смещение между двумя вызовами изменилось с минус пяти часов на минус четыре только потому, что одна метка времени приходится на летнее время, а другая нет. Интерфейс, который игнорирует это и применяет к обеим одно фиксированное смещение, ошибся бы на час в одном из случаев.
Почему важен параметр time
В большинстве мест, где переходят на летнее время, смещение меняется в течение года. Если вызывать эндпоинт без параметра time, вы получите сегодняшнее смещение, которое будет неверным для метки времени полугодовой давности. Всегда передавайте ту метку времени, которую преобразуете, а не текущее время, если они могут оказаться по разные стороны перехода на летнее время.
Кешируйте часовой пояс, а не смещение
Идентификатор часового пояса для заданных координат меняется редко, поэтому саму строку timezone можно спокойно кешировать для конкретного места. Значения utc_offset и abbreviation надолго кешировать нельзя, поскольку они меняются при переходе на летнее время, поэтому вычисляйте их заново при отображении, а не храните.
Пограничный случай, о котором стоит знать
Не во всех местах вообще переходят на летнее время. Место, где весь год действует фиксированное смещение, вернёт одинаковый utc_offset при любой переданной метке времени, и это ожидаемое поведение, а не признак того, что параметр time был проигнорирован. Не считайте, что одинаковый результат для двух разных меток времени означает поломку.
Стоимость запросов
Одно преобразование равно одному запросу. Панель, которая преобразует время сразу для множества сохранённых записей, должна отправлять соответствующие координаты пакетом через массовый POST, а не перебирать метки времени по одной: стоимость остаётся той же, один запрос на элемент, но всё делается одним вызовом.
Правильное местное время важнее, чем ожидает большинство команд, пока в обращении в поддержку не окажется неверный час. Подробности о полях запроса и ответа в документации по определению часового пояса.