Vous êtes prêt !

Pour passer à l'étape de développement, accédez à notre documentation pour les développeurs.

Activer Google Maps Time Zone API

Pour commencer, nous allons vous guider à travers la console Google Developers et effectuer deux ou trois petites choses :

  1. Créer ou sélectionner un projet
  2. Activer Google Maps Time Zone API
  3. Créer les clés appropriées
Continuer

Guide du développeur

Google Maps Time Zone API offre une interface simple qui permet d'obtenir le fuseau horaire d'un point géographique sur la Terre, ainsi que son décalage horaire par rapport à l'heure UTC.

Ce document est destiné aux développeurs de sites Web et d'applications mobiles qui souhaitent inclure des données horaires dans les cartes fournies par l'une des Google Maps API. Il contient une introduction à l'utilisation de cette API et des références sur les paramètres disponibles.

Introduction

Google Maps Time Zone API fournit les données de décalage horaire pour des points géographiques sur la Terre. Vous demandez les informations de fuseau horaire pour une paire latitude/longitude et une date spécifiques. L'API renvoie le nom du fuseau horaire, ainsi que le décalage par rapport à l'heure UTC et par rapport à l'heure d'été.

L'accès à Google Maps Time Zone API s'effectue via une interface HTTPS.

Avant de commencer à développer avec Time Zone API, consultez les exigences d'authentification (vous avez besoin d'une clé d'API) et les limites d'utilisation de l'API.

Requêtes de fuseau horaire

Les requêtes Google Maps Time Zone API se présentent sous la forme d'une chaîne URL. L'API renvoie des données de fuseau horaire pour un point de la Terre spécifié par une paire latitude/longitude. Notez que les données de fuseau horaire ne sont pas toujours disponibles pour les points géographiques immergés (mers et océans).

Les requêtes Google Maps Time Zone API ont la forme suivante :

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

outputFormat peut prendre l'une des valeurs suivantes :

  • json (recommandé), indique que la réponse doit être au format JSON (JavaScript Object Notation) ; ou
  • xml, indique que la réponse doit être au format XML, incorporée dans un nœud <TimeZoneResponse>.

Important : Vous devez envoyer les requêtes via https, et non pas via http.

Remarque : Les URL doivent être correctement encodées pour être valides et sont limitées à 8 192 caractères pour tous les services Web. Veillez à respecter cette limite lorsque vous élaborez vos URL. Notez que le nombre maximum de caractères de l'URL peut également varier selon le navigateur, le proxy ou le serveur.

Paramètres des requêtes

Comme pour toutes les URL, les paramètres sont séparés par le caractère esperluette (&). Vous trouverez ci-dessous la liste des paramètres et leurs différentes valeurs possibles.

Paramètres obligatoires

  • location — Paire de valeurs de latitude et longitude séparées par une virgule (location=-33.86,151.20, par exemple), représentant le point géographique à rechercher.
  • timestamp — Spécifie l'heure souhaitée, en secondes depuis le 1er janvier 1970 à minuit UTC. Google Maps Time Zone API utilise le paramètre timestamp pour déterminer si l'heure d'été doit être appliquée. Les heures antérieures à 1970 peuvent être exprimées sous forme de valeurs négatives.
  • key — Clé d'API de l'application. Cette clé identifie votre application à des fins de gestion des quotas. Découvrez comment obtenir une clé.

    Remarque : les clients Google Maps APIs Premium Plan peuvent utiliser soit une clé d'API, soit un ID client valide avec signature numérique dans leurs requêtes Time Zone. En savoir plus sur les paramètres d'authentification des clients Premium Plan.

Paramètres facultatifs

  • language — Langue dans laquelle les résultats sont renvoyés. Voir la liste des langues prises en charge. Notez que cette liste peut ne pas être exhaustive, car nous mettons régulièrement à jour les langues prises en charge. La valeur par défaut est en (anglais).

Réponses de fuseau horaire

Pour chaque requête valide, le service de fuseau horaire renvoie une réponse au format indiqué dans l'URL de la requête. Chaque réponse contient les éléments suivants :

  • dstOffset — Décalage de l'heure d'été en secondes. Sa valeur est nulle si le fuseau horaire ne se trouve pas en période d'heure d'été, d'après la valeur spécifiée pour le paramètretimestamp.
  • rawOffset — Décalage par rapport à l'heure UTC (en secondes) pour le point géographique donné. L'heure d'été n'est pas prise en compte.
  • timeZoneId — Chaîne contenant l'identifiant « tz » du fuseau horaire (« America/Los_Angeles » ou « Australia/Sydney », par exemple). Ces identifiants sont définis dans la base de données des fuseaux horaires de l'IANA, également disponible dans un format consultable dans l'article List of tz database time zones de Wikipédia.
  • timeZoneName — Chaîne contenant le nom complet du fuseau horaire. Ce champ est localisé si le paramètre de langue est défini (« Heure d'été du Pacifique » ou « Heure d'été de la côte Est de l'Australie », par exemple).
  • status — Chaîne indiquant le statut de la réponse.
    • OK indique que la requête a abouti.
    • INVALID_REQUEST indique que la requête a été mal formulée.
    • OVER_QUERY_LIMIT indique que le demandeur a dépassé le quota de requêtes autorisées.
    • REQUEST_DENIED indique que l'API n'a pas pu exécuter la requête. Vérifiez que la requête a été envoyée via HTTPS (et non via HTTP).
    • UNKNOWN_ERROR indique une erreur inconnue.
    • ZERO_RESULTS indique qu'aucune donnée de fuseau horaire n'a été identifiée pour l'heure ou la position spécifiée. Vérifiez que la requête concerne un point géographique terrestre (et non marin).
  • error_message — Informations plus détaillées sur le motif de ce code de statut, s'il est autre que OK.

    Remarque : La présence de ce champ n'est pas garantie et son contenu est susceptible de varier.

Calcul de l'heure locale

L'heure locale d'un point géographique donné est la somme des valeurs du paramètre timestamp et des champs dstOffset et rawOffset du résultat.

Exemples de requête

Cette section présente des exemples de requêtes qui illustrent les fonctionnalités de l'API.

La requête ci-dessous permet d'obtenir un fuseau horaire pour le Nevada, aux États-Unis. Le paramètre timestamp est défini sur le 8 mars 2012.

JSON

Requête :

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

Réponse :

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

Requête :

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

Réponse :

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

La requête ci-dessous permet d'obtenir un fuseau horaire pour le Nevada, aux États-Unis. Le point géographique est le même que ci-dessus, mais le paramètre timestamp est défini sur le 15 mars 2012. Cette fois, la réponse inclut un décalage par rapport à l'heure d'été.

JSON

Requête :

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

Réponse :

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

Requête :

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

Réponse :

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

Cet exemple est similaire aux deux précédents, mais définit un paramètre de langue. La réponse est donc localisée en espagnol.

JSON

Requête :

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

Réponse :

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

Requête :

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

Réponse :

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

Paramètre sensor

Google Maps API exigeait auparavant l'insertion du paramètre sensor pour savoir si votre application utilisait un capteur afin de déterminer la position géographique de l'utilisateur. Désormais, ce paramètre n'est plus obligatoire.

Envoyer des commentaires concernant…

Google Maps Time Zone API
Google Maps Time Zone API
Besoin d'aide ? Consultez notre page d'assistance.