Entwickler-Leitfaden

Die Google Maps Time Zone API bietet eine einfache Oberfläche zum Anfordern der Zeitzone für einen Standort sowie der Zeitverschiebung dieses Standorts von der UTC-Zeit.

Dieses Dokument richtet sich an Entwickler von Websites und mobilen Anwendungen, die Zeitangaben in Karten verwenden möchten, die über Google Maps APIs bereitgestellt werden. Es enthält eine Einführung zur Verwendung der API und Informationen zu den verfügbaren Parametern.

Einführung

Von der Google Maps Time Zone API werden Daten zur Zeitverschiebung für Standorte auf der Erde zurückgegeben. Sie fordern die Zeitzonendaten für bestimmte Längengrad- und Breitengradangaben und ein bestimmtes Datum an. Die API gibt den Namen der Zeitzone, die Abweichung von der UTC-Zeit und die Zeitverschiebung aufgrund der Sommerzeit zurück.

Der Zugriff auf die Google Maps Time Zone API erfolgt über eine HTTPS-Schnittstelle.

Bevor Sie mit der Durchführung von Entwicklungsaufgaben mit der Time Zone API beginnen, informieren Sie sich über die Authentifizierungsanforderungen (Sie benötigen einen API-Schlüssel) und die API-Nutzungsbeschränkungen.

Zeitzonen-Anforderungen

Google Maps Time Zone API-Anforderungen werden als URL-Zeichenfolge erstellt. Die API gibt Zeitzonendaten für einen Punkt auf der Erde zurück, der durch Längengrad- und Breitengradangaben bestimmt ist. Beachten Sie, dass für Punkte auf dem Wasser wie z. B. auf Meeren evtl. keine Zeitzonendaten verfügbar sind.

Eine Google Maps Time Zone API-Anforderung weist folgendes Format auf:

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, oder
• xml gibt die Ausgabe in XML an, in einem Knoten des Typs <TimeZoneResponse>.

Wichtig: Anforderungen müssen über https und nicht http über erfolgen.

Hinweis: URLs müssen ordnungsgemäß codiert sein, um gültig zu sein, und sind auf 8192 Zeichen für alle Webdienste beschränkt. Beachten Sie diese Beschränkung beim Erstellen Ihrer URLs. Zudem sollten Sie beachten, dass für verschiedene Browser, Proxys und Server ebenfalls unterschiedliche URL-Zeichenbegrenzungen gelten können.

Anforderungsparameter

Standardmäßig werden alle Parameter in URLs durch ein kaufmännisches Und (&) getrennt. Die Liste der Parameter und deren mögliche Werte sind unten aufgeführt.

Erforderliche Parameter

• location: ein durch Komma getrenntes Tupel mit Breiten- und Längengrad (z. B. location=-33.86,151.20) für den Standort, nach dem gesucht wird.
• timestamp gibt die gewünschte Zeit in Sekunden ab Mitternacht des 01.01.1970 UTC an. Die Google Maps Time Zone API verwendet den Parameter timestamp, um zu ermitteln, ob die Sommerzeit angewendet werden soll. Zeitangaben vor 1970 können als negative Werte ausgedrückt werden.
• key — der API-Schlüssel Ihrer Anwendung. Dieser Schlüssel identifiziert Ihre Anwendung für das Kontingentmanagement. So können Sie einen Schlüssel anfordern.

  Hinweis: Google Maps APIs Premium Plan-Kunden können entweder einen API-Schlüssel oder eine gültige Client-ID und eine digitale Signatur in Ihren Time Zone-Anforderungen verwenden. Lesen Sie weitere Informationen zu Authentifizierungsparametern für Premium Plan-Kunden.

Optionale Parameter

• language — die Sprache, in der die Ergebnisse zurückgegeben werden sollen. Weitere Informationen finden Sie in der Liste der unterstützten Domänensprachen. Beachten Sie, dass die unterstützten Sprachen häufig aktualisiert werden. Die Liste ist ggf. nicht vollständig. Der Standardwert ist en.

Antworten auf Zeitzonen-Anforderungen

Für jede gültige Anforderung gibt der Zeitzonen-Dienst eine Antwort in dem Format zurück, das in der Anforderungs-URL angegeben ist. In jeder Antwort sind die folgenden Elemente enthalten:

• dstOffset: die Zeitverschiebung aufgrund der Sommerzeit in Sekunden. Die Antwort ist null, wenn für die Zeitzone während des angegebenen timestamp nicht die Sommerzeit gilt.
• rawOffset: die Zeitverschiebung des Standorts von der UTC-Zeit in Sekunden. Hier wird die Sommerzeit nicht berücksichtigt.
• timeZoneId: eine Zeichenfolge mit der Zeitzonen-ID der Zeitzone, wie z. B. „America/Los_Angeles“ oder „Australia/Sydney“. Diese IDs sind in der IANA-Zeitzonendatenbank definiert und auch in der Liste der Zeitzonen-IDs der tz database der Wikipedia (in englischer Sprache) verzeichnet.
• timeZoneName: eine Zeichenfolge mit dem langen Namen der Zeitzone. Dieses Feld wird lokalisiert, wenn der Parameter „language“ festgelegt wurde. Beispiel: „Pacific Daylight Time“ oder „Australian Eastern Daylight Time“.
• status: eine Zeichenfolge, die den Status der Antwort angibt.
  • OK bedeutet, dass die Anforderung erfolgreich war.
  • INVALID_REQUEST bedeutet, dass die Anforderung fehlerhaft formatiert war.
  • OVER_QUERY_LIMIT gibt an, dass der Anforderer sein Kontingent überschritten hat.
  • REQUEST_DENIED gibt an, dass die API-Anforderung nicht ausgeführt wurde. Überprüfen Sie, ob die Anforderung über HTTPS und nicht über HTTP gesendet wurde.
  • UNKNOWN_ERROR gibt an, dass ein unbekannter Fehler vorliegt.
  • ZERO_RESULTS gibt an, dass für die angegebene Position oder Zeit keine Zeitzonendaten gefunden werden konnten. Überprüfen Sie, ob die Anforderung für einen Ort an Land und nicht über Wasser erfolgt ist.
• error_message: weitere detaillierte Informationen zu den Gründen für den zurückgegebenen Statuscode, wenn dieser nicht OK lautet.

  Hinweis: Dieses Feld wird nicht immer angezeigt, und sein Inhalt unterliegt Änderungen.

Berechnung der Ortszeit

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

Beispiele für Anforderungen

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 der 8. März 2012.

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

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

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

<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 oben, als Zeitstempel ist jedoch der 15. März 2012 festgelegt. Die Antwort enthält diesmal die Zeitverschiebung aufgrund der Sommerzeit.

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

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

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

<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. Daher wird die Antwort in Spanisch lokalisiert.

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

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

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

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

Der Parameter sensor

Bisher war in der Google Maps API die Angabe des Parameters sensor erforderlich. Damit wurde festgelegt, ob seitens der Anwendung ein Sensor zur Ermittlung des Benutzerstandorts verwendet wurde. Dieser Parameter wird nicht mehr benötigt.