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 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 emplacements situés au-dessus de l'eau, comme les océans ou les mers.

Une requête de fuseau horaire se présente comme suit :

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

où outputFormat peut prendre 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 <TimeZoneResponse> nœud.

Remarque : Les URL doivent être correctement encodées pour être valides et 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 d'URL différentes.

Paramètres obligatoires

• position

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

• timestamp

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

  Notez que l'API ne tient pas compte des fuseaux horaires historiques. Autrement dit, si vous spécifiez un timestamp passé, 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 renvoyer les résultats.

  • 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 fait de son mieux pour fournir une adresse postale lisible pour l'utilisateur et les habitants. Pour ce faire, 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 un nom n'est pas disponible dans la langue préférée, 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. Le timestamp est défini sur le 5 décembre 2024.

https://maps.googleapis.com/maps/api/timezone/json
  ?location=39.6034810%2C-119.6822510
  ×tamp=1733428634
  &key=YOUR_API_KEY

curl -L -X GET 'https://maps.googleapis.com/maps/api/timezone/json?location=39.6034810%2C-119.6822510×tamp=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. L'emplacement est le même que dans la requête ci-dessus, mais le timestamp est défini sur le 15 mars 2024. Cette fois, la réponse inclut un décalage par rapport à l'heure d'été.

https://maps.googleapis.com/maps/api/timezone/json
  ?location=39.6034810%2C-119.6822510
  ×tamp=1710547034
  &key=YOUR_API_KEY

curl -L -X GET 'https://maps.googleapis.com/maps/api/timezone/json?location=39.6034810%2C-119.6822510×tamp=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 est donc localisée en espagnol.

https://maps.googleapis.com/maps/api/timezone/json
  ?language=es
  &location=39.6034810%2C-119.6822510
  ×tamp=1710547034
  &key=YOUR_API_KEY

curl -L -X GET 'https://maps.googleapis.com/maps/api/timezone/json?location=39.6034810%2C-119.6822510×tamp=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 de fuseau horaire

Pour chaque requête valide, l'API Time Zone 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 Time Zone 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ées. Vérifiez que la requête concerne un emplacement sur terre et non au-dessus de l'eau.

Calcul de l'heure locale

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