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 Paar aus Breiten- und Längengrad angegeben wird. Für Orte über Wasser, z. B. Ozeane oder Meere, sind möglicherweise keine Zeitzonendaten verfügbar.

Eine Zeitzonenanfrage hat folgendes Format:

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

Dabei kann outputFormat einen der folgenden Werte haben:

  • json (empfohlen) gibt die Ausgabe in JavaScript Object Notation (JSON) an.
  • xml gibt die Ausgabe im XML-Format an, eingebettet in einen <TimeZoneResponse>-Knoten.

Erforderliche Parameter

Standort

Ein kommagetrenntes Tupel aus Breiten- und Längengrad (location=39.6034810,-119.6822510), das den Standort darstellt, der gesucht werden soll.

timestamp

Die gewünschte Zeit in Sekunden seit dem 1. Januar 1970, 00:00 Uhr UTC. Die Time Zone API verwendet den timestamp, um anhand der Zeitzone des location zu bestimmen, ob die Sommerzeit angewendet werden soll.

Die API berücksichtigt keine historischen Zeitzonen. Das heißt, wenn Sie einen Zeitstempel in der Vergangenheit angeben, berücksichtigt die API nicht, dass sich der Ort 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, sodass diese Liste unter Umständen nicht vollständig ist.
  • Wenn language nicht angegeben ist, versucht die API, die im Header Accept-Language angegebene bevorzugte Sprache zu verwenden.
  • Die API versucht, eine Adresse anzugeben, die sowohl für den Nutzer als auch für Einheimische lesbar ist. Dazu werden Adressen in der Landessprache zurückgegeben, die bei Bedarf in eine für den Nutzer lesbare Schrift transliteriert werden, wobei die bevorzugte Sprache berücksichtigt wird. Alle anderen Adressen werden in der bevorzugten Sprache zurückgegeben. Adresskomponenten werden alle in derselben Sprache zurückgegeben, die von der ersten Komponente ausgewählt wird.
  • Wenn ein Name in der bevorzugten Sprache nicht verfügbar ist, verwendet die API die nächstgelegene Übereinstimmung.
  • Die bevorzugte Sprache hat einen geringen Einfluss auf die von der API zurückgegebenen Ergebnisse und die Reihenfolge, in der sie zurückgegeben werden. Der Geocoder interpretiert Abkürzungen je nach Sprache unterschiedlich, z. B. Abkürzungen für Straßentypen oder Synonyme, die in einer Sprache gültig sind, 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 obigen Anfrage, aber der Zeitstempel ist auf den 15. März 2024 festgelegt. Die Antwort enthält jetzt einen Zeitversatz für die 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 auf Spanisch lokalisiert.

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>

Antworten zur Zeitzone

Für jede gültige Anfrage gibt die Zeitzone eine Antwort in dem Format zurück, das in der Anfrage-URL angegeben ist.

TimeZoneResponse

Feld Erforderlich Typ Beschreibung
required TimeZoneStatus Weitere Informationen finden Sie unter TimeZoneStatus.
optional Zahl

Die Abweichung für die Sommerzeit in Sekunden. Dieser Wert ist null, wenn die Zeitzone während der angegebenen timestamp nicht in der Sommerzeit liegt.

optional String

Detaillierte Informationen zu den Gründen für den angegebenen Statuscode. Enthalten, wenn der Status nicht Ok ist.

optional Zahl

Die Abweichung von UTC (in Sekunden) für den angegebenen Ort. Die Sommerzeit wird dabei nicht berücksichtigt.

optional String

Ein String, der die ID der Zeitzone enthält, z. B. „Europe/Berlin“ oder „Australia/Sydney“. Diese IDs werden vom Unicode Common Locale Data Repository (CLDR)-Projekt 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“.

optional String

Der Name der Zeitzone in Langform. 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 der Zeitzone 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 fehlerhaft war.

  • OVER_DAILY_LIMIT gibt einen der folgenden Werte an:

    • 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 gibt an, dass für die angegebene Position oder Zeit keine Zeitzonendaten gefunden werden konnten. Prüfen Sie, ob sich die Anfrage auf einen Standort an Land 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.