Surveillez l'utilisation de votre clé avant d'atteindre une limite
Surveiller vos en-têtes de quota au fil de l'eau vous indique quand une limite approche, bien avant qu'une requête ne soit effectivement refusée.
Convertir un horodatage UTC en heure locale pour vos utilisateurs
Stocker les horodatages en UTC est le bon choix pour une base de données. Afficher l'heure UTC à un utilisateur dans un ticket d'assistance, une confirmation de commande ou un journal d'activité ne l'est pas, et c'est l'une des petites frustrations les plus courantes dans l'interface d'un produit.
La conversion en deux étapes
D'abord, déterminez depuis quel lieu l'horodatage doit être interprété, soit les coordonnées d'une adresse enregistrée, soit les coordonnées issues d'une recherche d'IP. Ensuite, transmettez ces coordonnées et l'horodatage UTC lui-même à /v1/timezone avec le paramètre time, afin que le décalage renvoyé corresponde au moment en question plutôt qu'au moment présent.
GET /v1/timezone?lat=40.7128&lon=-74.0060&time=1734000000{
"status": "ok",
"timezone": "America/New_York",
"utc_offset": "-05:00",
"abbreviation": "EST"
}Appliquez le utc_offset à votre horodatage UTC stocké, ou transmettez l'identifiant de fuseau horaire à votre propre code de formatage des dates, et affichez le résultat au lieu de la valeur UTC brute.
Deuxième exemple, à plusieurs mois d'intervalle
Les mêmes coordonnées renvoient un décalage différent selon l'horodatage transmis, et c'est toute la raison d'être du paramètre time.
GET /v1/timezone?lat=40.7128&lon=-74.0060&time=1719000000{
"status": "ok",
"timezone": "America/New_York",
"utc_offset": "-04:00",
"abbreviation": "EDT"
}Remarquez que le décalage est passé de moins cinq heures à moins quatre heures entre les deux appels pour exactement le même lieu, uniquement parce que l'un des horodatages tombe pendant l'heure d'été et l'autre non. Un affichage qui ignorerait cela et appliquerait un même décalage fixe aux deux serait décalé d'une heure pour l'un d'eux.
Pourquoi le paramètre time compte
Le décalage change au cours de l'année dans la plupart des endroits qui appliquent l'heure d'été. Si vous appelez toujours l'endpoint sans paramètre time, vous obtenez le décalage du jour, qui sera faux pour un horodatage datant d'il y a six mois. Transmettez toujours l'horodatage que vous convertissez, et non l'heure actuelle, lorsque les deux peuvent se situer de part et d'autre d'un changement d'heure.
Mettre en cache le fuseau horaire, pas le décalage
L'identifiant de fuseau horaire associé à des coordonnées données change rarement : vous pouvez donc sans risque mettre en cache la chaîne timezone elle-même pour un lieu. Les valeurs utc_offset et abbreviation ne doivent pas être mises en cache longtemps, car elles varient avec l'heure d'été ; recalculez-les au moment de l'affichage plutôt que de les stocker.
Un cas limite à connaître
Tous les lieux n'appliquent pas l'heure d'été. Un lieu qui conserve un décalage fixe toute l'année renverra le même utc_offset quel que soit l'horodatage transmis, ce qui est le comportement attendu et non le signe que le paramètre time a été ignoré. Ne concluez pas qu'un résultat identique pour deux horodatages différents signifie que quelque chose ne fonctionne pas.
Le coût en requêtes
Une conversion correspond à une requête. Un tableau de bord qui convertit les heures de nombreux enregistrements à la fois devrait regrouper les coordonnées sous-jacentes dans un POST groupé plutôt que de boucler horodatage par horodatage : le coût reste d'une requête par élément, mais en un seul appel.
Afficher la bonne heure locale compte plus que la plupart des équipes ne l'imaginent, jusqu'au jour où un ticket d'assistance affiche la mauvaise heure. Le détail des champs de requête et de réponse figure dans la documentation de la recherche de fuseau horaire.