Zeitzonenanfragen und -antworten

Zeitzone

Time Zone API-Anfragen werden als URL-String erstellt. Die API gibt Zeitzonendaten für einen Punkt auf der Erde zurück, der durch ein Wertepaar aus Breitengrad und Längengrad angegeben wird. Für Orte auf dem Wasser, z. B. Ozeane oder Meere, sind möglicherweise keine Zeitzonendaten verfügbar.

Eine Zeitzonenanfrage hat das folgende Format:

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

Dabei kann outputFormat einer der folgenden Werte sein:

• json (empfohlen) gibt die Ausgabe in JavaScript Object Notation (JSON) an.
• xml: Gibt die Ausgabe in XML an, die in einem <TimeZoneResponse>-Knoten umschlossen ist.

Hinweis:URLs müssen richtig codiert sein, damit sie gültig sind. Außerdem sind sie für alle Webdienste auf 16.384 Zeichen beschränkt. Beachten Sie dieses Limit beim Erstellen Ihrer URLs. Unterschiedliche Browser, Proxys und Server können auch unterschiedliche Zeichenlimits für URLs haben.

Erforderliche Parameter

• Standort

  Ein durch Kommas getrenntes Tupel aus Breiten- und Längengrad,location=39.6034810,-119.6822510, das den Ort darstellt, der nachgeschlagen werden soll.

• timestamp

  Die beabsichtigte Zeit in Sekunden seit Mitternacht am 1. Januar 1970 (UTC). Die Time Zone API verwendet die timestamp, um anhand der Zeitzone der location zu ermitteln, ob die Sommerzeit angewendet werden soll.

  Bei der API werden keine historischen Zeitzonen berücksichtigt. Wenn Sie einen Zeitstempel aus der Vergangenheit angeben, berücksichtigt die API nicht, dass sich der Standort möglicherweise zuvor in einer anderen Zeitzone befunden hat.

Optionale Parameter

• Sprache

  Die Sprache, in der die Ergebnisse zurückgegeben werden sollen.

  • Hier finden Sie eine Liste der unterstützten Sprachen. Die unterstützten Sprachen werden regelmäßig von Google aktualisiert. Diese Liste ist daher möglicherweise nicht vollständig.
  • Wenn language nicht angegeben ist, versucht die API, die bevorzugte Sprache zu verwenden, die im Accept-Language-Header angegeben ist.
  • Die API versucht, eine Straßenadresse bereitzustellen, die sowohl für den Nutzer als auch für Einheimische lesbar ist. Dazu werden Straßenadressen in der lokalen Sprache zurückgegeben, die bei Bedarf in ein für den Nutzer lesbares Schriftsystem transliteriert werden. Dabei wird die bevorzugte Sprache berücksichtigt. Alle anderen Adressen werden in der bevorzugten Sprache zurückgegeben. Adresskomponenten werden alle in derselben Sprache zurückgegeben, die anhand der ersten Komponente ausgewählt wird.
  • Wenn ein Name in der bevorzugten Sprache nicht verfügbar ist, wird die nächstgelegene Übereinstimmung verwendet.
  • Die bevorzugte Sprache hat einen geringen Einfluss auf die Ergebnismenge, die von der API zurückgegeben wird, und auf die Reihenfolge, in der sie zurückgegeben werden. Der Geocoder interpretiert Abkürzungen je nach Sprache unterschiedlich, z. B. die Abkürzungen für Straßentypen oder Synonyme, die in einer Sprache gültig sein können, in einer anderen jedoch nicht. Beispiel: utca und tér sind Synonyme für „Straße“ auf Ungarisch.

Beispiele für Zeitzonen

In diesem Abschnitt sehen Sie einige Beispielabfragen, mit denen die Funktionen der API demonstriert werden.

Durch die folgende Abfrage wird eine Zeitzonenanforderung für Nevada, USA, durchgeführt. Der Zeitstempel ist auf den 5. Dezember 2024 festgelegt.

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>
      

Durch die folgende Abfrage wird eine Zeitzonenanforderung für Nevada, USA, durchgeführt. Der Standort ist derselbe wie in der Anfrage oben, der Zeitstempel ist jedoch auf den 15. März 2024 festgelegt. Die Antwort enthält jetzt eine Verschiebung aufgrund der Sommerzeit.

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>

Dieses Beispiel ähnelt den beiden obigen, es wird jedoch zusätzlich der Parameter „language“ festgelegt. Die Antwort wird jetzt ins Spanische übersetzt.

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>
      

Zeitzonenantworten

Für jede gültige Anfrage gibt der Time Zone-Dienst eine Antwort im Format zurück, das in der Anfrage-URL angegeben ist.

TimeZoneResponse

Feld	Erforderlich	Typ	Beschreibung
status	required	TimeZoneStatus	Weitere Informationen finden Sie unter TimeZoneStatus.
dstOffset	optional	Zahl	Die Verschiebung für die Sommerzeit in Sekunden. Dieser Wert ist null, wenn die Zeitzone während des angegebenen timestamp nicht auf Sommerzeit umgestellt wird.
errorMessage	optional	String	Detaillierte Informationen zu den Gründen für den angegebenen Statuscode. Enthalten, wenn der Status nicht Ok ist.
rawOffset	optional	Zahl	Die Abweichung von UTC (in Sekunden) für den angegebenen Ort. Die Umstellung auf Sommerzeit wird dabei nicht berücksichtigt.
timeZoneId	optional	String	Ein String mit der ID der Zeitzone, z. B. „America/Los_Angeles“ oder „Australia/Sydney“. Diese IDs werden vom Unicode Common Locale Data Repository (CLDR) definiert und sind derzeit in der Datei timezone.xml verfügbar. Wenn eine Zeitzone mehrere IDs hat, wird die kanonische ID zurückgegeben. In XML-Antworten ist dies der erste Alias jeder Zeitzone. Beispiel: „Asia/Calcutta“ wird zurückgegeben, nicht „Asia/Kolkata“.
timeZoneName	optional	String	Der vollständige Name der Zeitzone. Dieses Feld wird lokalisiert, wenn der Sprachparameter festgelegt ist, z. B. Pacific Daylight Time oder Australian Eastern Daylight Time.

TimeZoneStatus

Das Feld status im Antwortobjekt „Time Zone“ enthält den Status der Anfrage. Das Feld status kann die folgenden Werte enthalten:

• OK gibt an, dass die Anfrage erfolgreich war.

• INVALID_REQUEST gibt an, dass die Anfrage falsch formatiert war.

• OVER_DAILY_LIMIT bedeutet eine der folgenden Optionen:

  • Der API-Schlüssel fehlt oder ist ungültig.
  • Die Abrechnung wurde für Ihr Konto nicht aktiviert.
  • Das von Ihnen festgelegte Nutzungslimit wurde überschritten.
  • Die angegebene Zahlungsmethode ist nicht mehr gültig. Das kann z. B. bei einer abgelaufenen Kreditkarte der Fall sein.

• OVER_QUERY_LIMIT: Der Anforderer hat das Kontingent überschritten.

• REQUEST_DENIED gibt an, dass die API die Anfrage nicht abgeschlossen hat. Überprüfen Sie, ob die Anforderung über HTTPS und nicht über HTTP gesendet wurde.

• UNKNOWN_ERROR: Ein unbekannter Fehler ist aufgetreten.

• ZERO_RESULTS – Für die angegebene Position oder Zeit konnten keine Zeitzonendaten gefunden werden. Prüfen Sie, ob sich die Anfrage auf einen Ort auf dem Festland und nicht auf dem Wasser bezieht.

Ortszeit berechnen

Die Ortszeit eines bestimmten Standorts ist die Summe aus dem Parameter timestamp und den Feldern dstOffset und rawOffset aus dem Ergebnis.