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 des données de fuseau horaire pour un point sur la 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 de fuseau horaire se présente sous la forme suivante :

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

où outputFormat peut avoir l'une des valeurs suivantes :

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

Remarque : Pour être valides, les URL doivent être correctement encodées. Elles sont limitées à 16 384 caractères pour tous les services Web. Tenez compte de cette limite lorsque vous créez vos URL. Notez que différents navigateurs, proxys et serveurs peuvent également avoir des limites de caractères différentes pour les URL.

Paramètres obligatoires

• position

  Tuple latitude,longitude séparé par une virgule, location=39.6034810,-119.6822510, représentant le lieu à rechercher.

• timestamp

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

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

Paramètres facultatifs

• language

  Langue dans laquelle renvoyer les résultats.

  • Consultez la liste des langues disponibles. 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 met tout en œuvre pour fournir une adresse postale lisible à la fois pour l'utilisateur et les habitants. Pour atteindre cet objectif, il 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 de préférence. Les composants d'adresse sont tous renvoyés dans la même langue, qui est choisie à partir du premier composant.
  • Si un nom n'est pas disponible dans la langue de votre choix, l'API utilise la correspondance la plus proche.
  • La langue préférée a une faible influence sur l'ensemble des résultats que l'API choisit de renvoyer et sur l'ordre dans lequel ils sont renvoyés. Le géocoder 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. L'horodatage est défini sur le 5 décembre 2024.

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

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

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

<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. La localisation est la même que dans 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 pour l'heure d'été.

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

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

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

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

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

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'

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

<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 Fuseaux horaires renvoie une réponse au format indiqué dans l'URL de la requête.

TimeZoneResponse

TimeZoneStatus

Le champ status de l'objet de réponse du 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 était mal formulée.

• 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 pour 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ées. Confirmez que la demande concerne un lieu sur terre et non sur l'eau.

Calcul de l'heure locale

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