Requêtes et réponses de fuseau horaire

Fuseau horaire

Les requêtes de l'API Time Zone sont construites sous forme de chaîne d'URL. L'API renvoie les données de fuseau horaire d'un point sur Terre, spécifié par une paire latitude-longitude. Notez que les données de fuseau horaire peuvent ne pas être disponibles pour les lieux situés sur l'eau, comme les océans ou les mers.

Une requête Time Zone se présente sous la forme suivante :

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

où outputFormat peut correspondre à l'une des valeurs suivantes :

  • json (recommandé), indique une sortie au format JavaScript Object Notation (JSON) ; ou
  • xml, indique une sortie au format XML, encapsulée dans un nœud <TimeZoneResponse>.

Paramètres obligatoires

position

Un tuple latitude,longitude séparé par une virgule, location=39.6034810,-119.6822510, représentant l'emplacement à rechercher.

code temporel

Heure prévue en secondes depuis le 1er janvier 1970 à minuit UTC. L'API Time Zone utilise le timestamp pour déterminer si l'heure d'été doit être appliquée, en fonction du fuseau horaire de l'location.

Notez que l'API ne tient pas compte des fuseaux horaires historiques. En d'autres termes, si vous spécifiez un code temporel antérieur, l'API ne tient pas compte de la possibilité que l'emplacement se trouvait auparavant dans un autre fuseau horaire.

Paramètres facultatifs

language

Langue dans laquelle les résultats doivent être renvoyés.

  • Consultez la liste des langues acceptées. Google met souvent à jour les langues acceptées. Cette liste n'est donc pas exhaustive.
  • Si language n'est pas fourni, l'API tente d'utiliser la langue préférée spécifiée dans l'en-tête Accept-Language.
  • L'API s'efforce de fournir une adresse postale lisible à la fois pour l'utilisateur et pour les habitants. Pour atteindre cet objectif, elle renvoie les adresses postales dans la langue locale, translittérées dans un script lisible par l'utilisateur si nécessaire, en respectant la langue préférée. Toutes les autres adresses sont renvoyées dans la langue préférée. Les composants d'adresse sont tous renvoyés dans la même langue, qui est choisie à partir du premier composant.
  • Si aucun nom n'est disponible dans la langue préférée, l'API utilise la correspondance la plus proche.
  • La langue préférée a une légère influence sur l'ensemble des résultats que l'API choisit de renvoyer et sur l'ordre dans lequel ils sont renvoyés. Le geocoder interprète les abréviations différemment selon la langue, par exemple les abréviations des types de rues ou les synonymes qui peuvent être valides dans une langue, mais pas dans une autre. Par exemple, utca et tér sont des synonymes de "rue" en hongrois.

Exemples de fuseaux horaires

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 code temporel est défini sur le 5 décembre 2024.

URL

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

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/timezone/json?location=39.6034810,-119.6822510&timestamp=1733428634&key=YOUR_API_KEY'

JSON

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

XML

<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. L'emplacement est le même que pour la requête ci-dessus, mais le code temporel est défini sur le 15 mars 2024. La réponse inclut désormais un décalage d'heure d'été.

URL

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

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/timezone/json?location=39.6034810,-119.6822510&timestamp=1710547034&key=YOUR_API_KEY'

JSON

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

XML

<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 sera désormais localisée en espagnol.

URL

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

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/timezone/json?location=39.6034810,-119.6822510&timestamp=1710547034&language=es&key=YOUR_API_KEY'

JSON

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

XML

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

Réponses sur les fuseaux horaires

Pour chaque requête valide, le service Fuseau horaire renvoie une réponse au format indiqué dans l'URL de la requête.

TimeZoneResponse

Champs Obligatoire Type Description
required TimeZoneStatus Pour en savoir plus, consultez TimeZoneStatus.
facultatif nombre

Décalage pour l'heure d'été en secondes. Cette valeur est égale à zéro si le fuseau horaire n'est pas à l'heure d'été pendant la période timestamp spécifiée.

facultatif chaîne

Informations détaillées sur les raisons du code d'état donné. Inclus si l'état est différent de Ok.

facultatif nombre

Décalage par rapport à UTC (en secondes) pour l'emplacement donné. Cela ne tient pas compte de l'heure d'été.

facultatif chaîne

Chaîne contenant l'ID du fuseau horaire, par exemple "America/Los_Angeles" ou "Australia/Sydney". Ces ID sont définis par le projet Unicode Common Locale Data Repository (CLDR) et sont actuellement disponibles dans le fichier timezone.xml. Lorsqu'un fuseau horaire comporte plusieurs ID, l'ID canonique est renvoyé. Dans les réponses XML, il s'agit du premier alias de chaque fuseau horaire. Par exemple, "Asia/Calcutta" est renvoyé, et non "Asia/Kolkata".

facultatif chaîne

Nom long du fuseau horaire. Ce champ sera localisé si le paramètre de langue est défini. Par exemple : Pacific Daylight Time ou Australian Eastern Daylight Time.

TimeZoneStatus

Le champ status de l'objet de réponse Fuseau horaire contient l'état de la requête. Le champ status peut contenir les valeurs suivantes :

  • OK indique que la requête a abouti.

  • INVALID_REQUEST indique que la requête n'a pas été rédigée correctement.

  • OVER_DAILY_LIMIT indique l'un des éléments suivants :

    • La clé API est manquante ou non valide.
    • La facturation n'a pas été activée sur votre compte.
    • La limite d'utilisation que vous avez définie vous-même a été dépassée.
    • Le mode de facturation fourni n'est plus valide (une carte de crédit est arrivée à expiration, par exemple).

  • OVER_QUERY_LIMIT indique que le demandeur a dépassé le quota.

  • REQUEST_DENIED indique que l'API n'a pas terminé 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é trouvée pour la position ou l'heure spécifiée. Vérifiez que la requête concerne un emplacement sur terre et non sur l'eau.

Calcul de l'heure locale…

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