Die Nutzung Ihres Schlüssels überwachen, bevor Sie an ein Limit stoßen
Wenn Sie Ihre Kontingent-Header laufend beobachten, wissen Sie, wann ein Limit näher rückt, lange bevor eine Anfrage tatsächlich abgelehnt wird.
Die Zeitzone für beliebige Breiten- und Längengrade ermitteln
Koordinaten allein verraten Ihnen nicht, wie spät es an einem Punkt auf der Karte ist. Der Zeitzonen-Endpunkt nimmt Breiten- und Längengrad entgegen und gibt den Namen der Zeitzone, ihren aktuellen UTC-Offset und ihre Abkürzung zurück.
Die Anfrage stellen
GET /v1/timezone?lat=52.3676&lon=4.9041{
"status": "ok",
"timezone": "Europe/Amsterdam",
"utc_offset": "+02:00",
"abbreviation": "CEST"
}Das Feld timezone ist ein Standardbezeichner, den Sie direkt an die meisten Datums- und Zeitbibliotheken übergeben können. Die Felder utc_offset und abbreviation sind für die Anzeige nützlich, wenn Sie Lesern etwas Vertrauteres zeigen möchten als eine Bezeichner-Zeichenkette.
Ein zweites Beispiel, jenseits der Datumsgrenze
Offsets sind nicht immer kleine, runde Zahlen, und manche Orte liegen, von der Mehrheit der Weltbevölkerung aus gesehen, auf der anderen Seite der Datumsgrenze.
GET /v1/timezone?lat=-17.7333&lon=168.3273{
"status": "ok",
"timezone": "Pacific/Efate",
"utc_offset": "+11:00",
"abbreviation": "VUT"
}Behandeln Sie den zurückgegebenen Bezeichner immer gleich, egal wie weit er von der Uhr Ihres eigenen Servers entfernt ist. Ihre Datumsbibliothek weiß bereits, wie sie einen Offset von elf Stunden korrekt verarbeitet, Sie müssen also für Orte weit entfernt von Ihrer eigenen Zeitzone keinen Sonderfall schreiben.
Kombination mit Geokodierung
Dieser Endpunkt benötigt nur Koordinaten und passt daher gut zur Geokodierung und Reverse-Geokodierung. Geokodieren Sie zuerst eine Adresse, um ihren Breiten- und Längengrad zu erhalten, und übergeben Sie diese dann direkt an /v1/timezone, um herauszufinden, in welcher Zone dieser Ort liegt, ohne den Nutzer direkt nach Zeitzonen zu fragen.
Eine verwandte Abkürzung
Wenn Sie bereits die IP-Adresse eines Besuchers statt einer geokodierten Adresse haben, gibt der Endpunkt /v1/ip in seiner eigenen Antwort direkt ein Feld timezone zurück, ganz ohne separaten Aufruf dieses Endpunkts. Greifen Sie direkt auf /v1/timezone zurück, wenn Sie bereits Koordinaten ohne zugehörige IP-Abfrage haben, etwa eine Adresse aus dem Versandprofil eines Kunden.
Sommerzeit berücksichtigen
Die Werte utc_offset und abbreviation geben den Offset wieder, der zum abgefragten Zeitpunkt gilt. Wenn Sie ein bestimmtes Datum statt des aktuellen Zeitpunkts interessiert, übergeben Sie mit dem Parameter time einen Unix-Zeitstempel, damit die Antwort den Offset widerspiegelt, der an diesem Datum galt, und nicht den heutigen.
GET /v1/timezone?lat=52.3676&lon=4.9041&time=1731000000Ein Fehler, den Sie vermeiden sollten
Diesen Endpunkt einmal aufzurufen und den Wert utc_offset langfristig zu speichern, ist eine verbreitete Abkürzung, die an Orten mit Sommerzeit zweimal im Jahr versagt. Der Zeitzonen-Bezeichner selbst ist stabil und kann bedenkenlos gespeichert werden. Offset und Abkürzung dagegen nicht, da sie sich mit dem Kalender verschieben. Berechnen Sie sie daher zum Zeitpunkt der Anzeige neu, statt sie zusammen mit dem Bezeichner zu speichern.
Was es kostet
Jede Zeitzonen-Abfrage ist eine Anfrage. Wenn Sie im Rahmen eines Registrierungs- oder Checkout-Ablaufs bereits eine Adresse geokodieren, verdoppelt eine zusätzliche Zeitzonen-Abfrage für denselben Ort die Anzahl der Anfragen für diesen Ablauf von einer auf zwei, was gemessen an den 2.500 kostenlosen Anfragen pro Tag, die in jedem Schlüssel enthalten sind, immer noch unbedeutend ist.
Zeitzonendaten sind von Hand leicht falsch zu pflegen, besonders rund um die Umstellung auf Sommerzeit. Es lohnt sich daher, sie aus einer einzigen Quelle zu beziehen, statt eine eigene Offset-Tabelle zu pflegen. Die Dokumentation zur Zeitzonen-Abfrage enthält die vollständige Parameterliste.