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.

URL

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

curl

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

URL

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

curl

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

URL

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

curl

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'

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

Champ	Obligatoire	Type	Description
`status`	required	TimeZoneStatus	Pour en savoir plus, consultez la page relative à TimeZoneStatus.
`dstOffset`	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 le `timestamp` spécifié `timestamp`.
`errorMessage`	facultatif	chaîne	Informations détaillées sur les raisons du code d'état donné. Inclus si l'état est différent de `Ok`.
`rawOffset`	facultatif	nombre	Décalage par rapport à l'heure UTC (en secondes) pour l'emplacement donné. Cela ne tient pas compte de l'heure d'été.
`timeZoneId`	facultatif	chaîne	Chaîne contenant l'ID du fuseau horaire, tel que "America/Los_Angeles" ou "Australia/Sydney". Ces ID sont définis par le projet CLDR (Common Locale Data Repository) d'Unicode 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".
`timeZoneName`	facultatif	chaîne	Nom complet du fuseau horaire. Ce champ est 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 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.

Requêtes et réponses de fuseau horaire

Fuseau horaire

Paramètres obligatoires

position

timestamp

Paramètres facultatifs

language

Exemples de fuseaux horaires

URL

curl

JSON

XML

URL

curl

JSON

XML

URL

curl

JSON

XML

Réponses de fuseau horaire

TimeZoneResponse

`status`

`dstOffset`

`errorMessage`

`rawOffset`

`timeZoneId`

`timeZoneName`

TimeZoneStatus

Calcul de l'heure locale

Requêtes et réponses de fuseau horaire Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

Fuseau horaire

Paramètres obligatoires

position

timestamp

Paramètres facultatifs

language

Exemples de fuseaux horaires

URL

curl

JSON

XML

URL

curl

JSON

XML

URL

curl

JSON

XML

Réponses de fuseau horaire

TimeZoneResponse

status

dstOffset

errorMessage

rawOffset

timeZoneId

timeZoneName

TimeZoneStatus

Calcul de l'heure locale

Requêtes et réponses de fuseau horaire

`status`

`dstOffset`

`errorMessage`

`rawOffset`

`timeZoneId`

`timeZoneName`