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.
Einen UTC-Zeitstempel für Ihre Nutzer in Ortszeit umrechnen
Zeitstempel in UTC zu speichern ist für eine Datenbank die richtige Entscheidung. Einem Nutzer UTC in einem Support-Ticket, einer Bestellbestätigung oder einem Aktivitätsprotokoll anzuzeigen, ist es nicht, und es gehört zu den häufigeren kleinen Ärgernissen in der Oberfläche eines Produkts.
Die Umrechnung in zwei Schritten
Erstens: Sie müssen wissen, von welchem Ort aus der Zeitstempel interpretiert werden soll, entweder anhand der Koordinaten einer hinterlegten Adresse oder der Koordinaten aus einer IP-Abfrage. Zweitens: Übergeben Sie diese Koordinaten und den UTC-Zeitstempel selbst über den Parameter time an /v1/timezone, damit die zurückgegebene Zeitverschiebung zum betreffenden Zeitpunkt passt und nicht zum aktuellen.
GET /v1/timezone?lat=40.7128&lon=-74.0060&time=1734000000{
"status": "ok",
"timezone": "America/New_York",
"utc_offset": "-05:00",
"abbreviation": "EST"
}Wenden Sie utc_offset auf Ihren gespeicherten UTC-Zeitstempel an oder übergeben Sie die Zeitzonenkennung an Ihren eigenen Code zur Datumsformatierung, und zeigen Sie das Ergebnis statt des rohen UTC-Werts an.
Ein zweites Beispiel, Monate später
Dieselben Koordinaten liefern je nach übergebenem Zeitstempel eine andere Zeitverschiebung, und genau deshalb gibt es den Parameter time.
GET /v1/timezone?lat=40.7128&lon=-74.0060&time=1719000000{
"status": "ok",
"timezone": "America/New_York",
"utc_offset": "-04:00",
"abbreviation": "EDT"
}Beachten Sie, dass sich die Zeitverschiebung zwischen den beiden Aufrufen für exakt denselben Ort von minus fünf auf minus vier Stunden verändert hat, allein weil ein Zeitstempel in die Sommerzeit fällt und der andere nicht. Eine Anzeige, die das ignoriert und auf beide eine einzige feste Zeitverschiebung anwendet, läge bei einem von beiden eine Stunde daneben.
Warum der Parameter time wichtig ist
An den meisten Orten mit Sommerzeit ändert sich die Zeitverschiebung im Laufe des Jahres. Wenn Sie den Endpunkt immer nur ohne den Parameter time aufrufen, erhalten Sie die heutige Zeitverschiebung, die für einen Zeitstempel von vor sechs Monaten falsch ist. Übergeben Sie immer den Zeitstempel, den Sie umrechnen, und nicht die aktuelle Uhrzeit, wenn die beiden auf verschiedenen Seiten einer Sommerzeitumstellung liegen könnten.
Die Zeitzone cachen, nicht die Zeitverschiebung
Die Zeitzonenkennung für bestimmte Koordinaten ändert sich selten, daher können Sie die timezone-Zeichenfolge selbst bedenkenlos für einen Standort cachen. Die Werte utc_offset und abbreviation sollten Sie dagegen nicht lange cachen, da sie sich mit der Sommerzeit verschieben. Berechnen Sie diese deshalb zum Zeitpunkt der Anzeige neu, statt sie zu speichern.
Ein Sonderfall, den Sie kennen sollten
Nicht jeder Ort kennt überhaupt eine Sommerzeit. Ein Ort, der das ganze Jahr über bei einer festen Zeitverschiebung bleibt, liefert unabhängig vom übergebenen Zeitstempel denselben utc_offset. Das ist erwartetes Verhalten und kein Zeichen dafür, dass der Parameter time ignoriert wurde. Schließen Sie aus einem gleichen Ergebnis für zwei verschiedene Zeitstempel nicht, dass etwas kaputt ist.
Kosten der Anfragen
Eine Umrechnung ist eine Anfrage. Ein Dashboard, das Uhrzeiten für viele gespeicherte Datensätze auf einmal umrechnet, sollte die zugrunde liegenden Koordinaten per Bulk-POST bündeln, statt einen Zeitstempel nach dem anderen in einer Schleife abzufragen. Die Kosten bleiben bei einer Anfrage pro Eintrag, aber in einem einzigen Aufruf.
Die richtige Ortszeit ist wichtiger, als die meisten Teams erwarten, bis ein Support-Ticket die falsche Stunde anzeigt. Details zu den Anfrage- und Antwortfeldern finden Sie in der Dokumentation zur Zeitzonenabfrage.