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.
Trouver le fuseau horaire de n'importe quelle latitude et longitude
Des coordonnées seules ne vous disent pas quelle heure il est en un point de la carte. L'endpoint de fuseau horaire prend une latitude et une longitude et renvoie le nom du fuseau horaire, son décalage UTC actuel et son abréviation.
Envoyer la requête
GET /v1/timezone?lat=52.3676&lon=4.9041{
"status": "ok",
"timezone": "Europe/Amsterdam",
"utc_offset": "+02:00",
"abbreviation": "CEST"
}Le champ timezone est un identifiant standard que vous pouvez transmettre directement à la plupart des bibliothèques de date et d'heure. Les champs utc_offset et abbreviation sont utiles pour l'affichage, lorsque vous voulez montrer au lecteur quelque chose de plus familier qu'une chaîne d'identifiant.
Un second exemple, de l'autre côté de la ligne de changement de date
Les décalages ne sont pas toujours de petits nombres ronds, et certains lieux se trouvent de l'autre côté de la ligne de changement de date par rapport à la majeure partie de la population mondiale.
GET /v1/timezone?lat=-17.7333&lon=168.3273{
"status": "ok",
"timezone": "Pacific/Efate",
"utc_offset": "+11:00",
"abbreviation": "VUT"
}Traitez l'identifiant renvoyé de la même manière, quelle que soit la distance qui le sépare de l'horloge de votre propre serveur. Votre bibliothèque de dates sait déjà gérer correctement un décalage de onze heures : il n'y a donc aucun cas particulier à écrire pour les lieux éloignés de votre propre fuseau horaire.
Le combiner avec le géocodage
Cet endpoint n'a besoin que de coordonnées, il se combine donc naturellement avec le géocodage direct ou inverse. Géocodez d'abord une adresse pour obtenir sa latitude et sa longitude, puis transmettez-les directement à /v1/timezone pour savoir dans quel fuseau se trouve ce lieu, sans rien demander directement à l'utilisateur sur les fuseaux horaires.
Un raccourci utile
Si vous disposez déjà de l'adresse IP d'un visiteur plutôt que d'une adresse géocodée, l'endpoint /v1/ip renvoie directement un champ timezone dans sa propre réponse, sans aucun appel séparé à cet endpoint. Utilisez /v1/timezone directement lorsque vous avez déjà des coordonnées sans recherche d'IP associée, par exemple une adresse issue du profil de livraison d'un client.
Tenir compte de l'heure d'été
Les champs utc_offset et abbreviation reflètent le décalage en vigueur au moment demandé. Si une date précise vous intéresse plutôt que l'instant présent, passez un horodatage Unix avec le paramètre time afin que la réponse reflète le décalage applicable à cette date, et non celui d'aujourd'hui.
GET /v1/timezone?lat=52.3676&lon=4.9041&time=1731000000Une erreur à éviter
Appeler cet endpoint une seule fois et mettre en cache la valeur utc_offset sur le long terme est un raccourci courant qui ne fonctionne plus deux fois par an dans les lieux qui appliquent l'heure d'été. L'identifiant du fuseau horaire est stable et peut être mis en cache sans risque. Le décalage et l'abréviation ne le sont pas, puisqu'ils évoluent avec le calendrier : recalculez-les au moment de l'affichage au lieu de les stocker à côté de l'identifiant.
Ce que cela coûte
Chaque recherche de fuseau horaire correspond à une requête. Si vous géocodez déjà une adresse dans un parcours d'inscription ou de paiement, ajouter une recherche de fuseau horaire pour le même lieu double votre nombre de requêtes pour ce parcours, qui passe d'une à deux, ce qui reste négligeable face aux 2 500 requêtes gratuites par jour incluses avec chaque clé.
Les données de fuseau horaire sont faciles à mal gérer à la main, surtout autour des passages à l'heure d'été : mieux vaut donc les tirer d'une source unique plutôt que de maintenir votre propre table de décalages. La documentation de la recherche de fuseau horaire présente la liste complète des paramètres.