API - Für Ihre Website

Um einen Ort aus dem wetter.com Datenbestand eindeutig zu identifizieren benötigt man einen sogenannten wetter.com city code.

Der city code ist eine Mischung aus Buchstaben und Zahlen. Der city code von Berlin ist DE0001020.
DE zeigt an, dass die Stadt in Deutschland liegt, die restlichen Stellen identifizieren den Ort. Stadtteile einer Stadt haben einen längeren city code, der von Berlin Tempelhof lautet zum Beispiel DE0001020466

Soll eine Anwendung nur das Wetter für eine bestimmte, vorher festgelegte Stadt liefern, ist es nicht nötig den city code für diese Stadt jedesmal dynamisch zu holen.Die einfachere Methode wäre hier, auf www.wetter.com den Ort über die Schnellsuche zu suchen und den Wert des 'id' Parameters aus der URL zu kopieren.

Für komplexere Anwendungen empfiehlt es sich oft, dem Benutzer selbst die Auswahl des Orts zu überlassen. Hierzu können Sie eine Anfrage an die openweather Schnittstelle schicken, die Informationen für alle Suchergebnisse eines Begriffs zurück liefert. Diese Liste kann dem Benutzer Präsentiert werden, um die Auswahl zu erleichtern.

Suchmöglichkeiten
Je nach Anwendungsfall macht es Sinn, die Suche so offen wie möglich zu halten oder sie einzuschränken. Hierfür gibt es mehrere Suchmöglichkeiten mit der wetter.com openweather Schnittstelle.

Gemischte Suche

Die von spitzen Klammern eingeschlossenen Variablen müssen ersetzt werden. Der Suchbegriff kann hierbei ein Stadt- oder Regionsname, eine Postleitzahl oder eine Mischung aus beiden sein.

Der Projektname wird beim Anlegen eines Projekts festgelegt und kann in den Projekteinstellungen eingesehen werden.

Die Checksumme wird aus dem Suchbegriff, dem Projekt Namen und dem API Key gebildet. Näheres hierzu lesen Sie im Kapitel "Authentifizierungsverfahren".

Namenssuche

Die von spitzen Klammern eingeschlossenen Variablen müssen ersetzt werden. Der Suchbegriff kann hierbei ein Stadt- oder Regionsname, eine Postleitzahl oder eine Mischung aus beiden sein.

Der Projektname wird beim Anlegen eines Projekts festgelegt und kann in den Projekteinstellungen eingesehen werden.

Die Checksumme wird aus dem Suchbegriff, dem Projekt Namen und dem API Key gebildet. Näheres hierzu lesen Sie im Kapitel "Authentifizierungsverfahren".

Postleitzahlensuche

Die von spitzen Klammern eingeschlossenen Variablen müssen ersetzt werden. Der Suchbegriff kann hierbei ein Stadt- oder Regionsname, eine Postleitzahl oder eine Mischung aus beiden sein. Der Suchbegriff muss hierbei eine Zahl mit mindestens 4, maximal 5 Stellen sein. Die Postleitzahlensuche beschränkt sich auf Deutschland, Österreich und die Schweiz.

Der Projektname wird beim Anlegen eines Projekts festgelegt und kann in den Projekteinstellungen eingesehen werden.

Die Checksumme wird aus dem Suchbegriff, dem Projekt Namen und dem API Key gebildet. Näheres hierzu lesen Sie im Kapitel "Authentifizierungsverfahren".

Weiteres Vorgehen
Hat man die Anfrage abgeschickt antwortet die wetter.com openweather Schnittstelle entweder mit einer Fehlermeldung oder mit dem Ergebnis der Suche. Sie sollten in Ihrer Programmierung auf jeden Fall Sorge dafür tragen, dass ein Fehler als Antwort entsprechend behandelt wird. In der Projektverwaltung können Sie einstellen, welche Werte von der Suche zurück geliefert werden und erfahren auch, was diese bedeuten.

Hat man den wetter.com city code eines Ortes, kann man für diesen die Wettervorhersage abfragen. Wie man den city code zu einem Ort findet, ist im Kapitel "Suchanfrage" beschrieben.

Die Abfrage einer Wettervorhersage läuft genauso ab, wie die Suchabfrage. Eine Anwendung ruft eine URL mit bestimmten Parametern auf und bekommt als Antwort ein Dokument in einem vorher festgelegten Format.

Die Wettervorhersage wird maximal für Heute plus zwei Tage geliefert. Benötigt man weniger Daten, kann dies in den Projekteinstellungen entsprechend konfiguriert werden. Für jeden Tag gibt es vier Vorhersagezeitpunkte: morgens, mittags, abends und nachts. Dies ist definiert durch einen Zeitpunkt in lokaler Zeit für diesen Ort und ein Attribut, welches die Gültigkeitsdauer dieses Vorhersagezeitpunkts beschreibt. Um ein Beispiel für diese Vorhersagepunkte zu sehen, kann man auf www.wetter.com in der Schnellsuche nach einem Ort suchen. Scrollt man hier etwas nach unten sieht man die Vorhersage mit den 4 Messzeitpunkten (der kleine blaue Pfeil rechts oben in den Vorhersagekästen enthüllt die Vorhersage für die Nacht).

Zusätzlich zu den vier Messpunkten gibt es einen aus der Vorhersage errechneten Tagesdurchschnitt, der direkt unterhalb des Tagesknotens zu finden ist.

Ausführen einer Vorhersageanfrage
Um eine Wettervorhersage zu erhalten, schickt man einen HTTP Request an

Die in spitzen Klammern gefassten Variablen müssen durch die entsprechenden Werte für das Projekt und die Anfrage ersetzt werden.

CityCode ist der wetter.com City Code, den man entweder statisch gespeichert hat oder dynamisch über die openweather Schnittstelle beziehen kann. Projektname ist der Name des Projekts und kann in den Projekteinstellungen nachgelesen werden. Die Checksumme ist ein MD5 Hash über einen zusammengefassten String aus Projektname, API Key und City Code, siehe auch "Authentifizierungsverfahren".

Weiteres Vorgehen
Hat man diese Abfrage abgeschickt, antwortet der Server in einem in den Projekteinstellungen definierten Format. Die Antwort enthält entweder einen Fehler oder eine Vorhersage. In der Projektverwaltung können Sie einstellen, welche Werte zurück geliefert werden sollen und erfahren, was diese bedeuten.

Um eine Städtesuche oder eine Wettervorhersage für eine eigene Anwendung mit der wetter.com openweather Schnittstelle auszuführen, müssen die folgenden Voraussetzungen erfüllt sein:

• der Anwendungsersteller muss auf www.wetter.com registriert sein
• der Anwendungsersteller muss ein Projekt für seine Anwendung erstellt haben
• die Anfrage muss sich durch Übergabe verschiedener Parameter im GET-Request (in der URL) authentifizieren.

In diesem Dokument wird die dritte Voraussetzung näher beschrieben.

Authentifizierung bei einer Suchanfrage
Einer Suchanfrage müssen drei Informationen übergeben werden, der zu suchende Begriff, der Projektname und eine Checksumme.

Die Checksumme ist ein MD5-Hash aus dem Projektnamen, dem API Key und dem Suchbegriff. Der Projektname sowie der API Key werden beim Anlegen eines Projekts festgelegt und können in den Projektinformationen eingesehen werden.

Das folgende Beispiel zeigt, wie in der Programmiersprache PHP ein Suchrequest zusammengebaut werden würde. Projektname ist hierbei "beispielprojekt", der API Key lautet "geheim" (in der Wirklichkeit wäre er ein eine längere Zeichenfolge aus HEX-Charakteren). Gesucht wird nach "Berlin".

            <?php
            $sSearchUrl     = 'http://api.wetter.com/location/index';
            $sProjectName   = 'beispielprojekt';
            $sApiKey        = 'geheim';
            $sSearchString  = 'Berlin';

            // Generieren der Checksumme, muss für jeden neuen Suchstring berechnet werden
            $sChecksum  = md5($sProjectName . $sApiKey . $sSearchString);

            $sSearchUrl .= '/search/' . $sSearchString;
            $sSearchUrl .= '/project/' . $sProjectName;
            $sSearchUrl .= '/cs/' . $sChecksum;
            ?>
        

Am Ende des Scripts wäre $sSearchUrl gleich

Natürlich sollte man in einem richtigen Projekt das ganze etwas dynamischer halten, aber zu Demonstrationszwecken sollte obiges Beispiel genügen.

Es spielt übrigens keine Rolle ob man, wie in obigem Beispiel, eine gemischte Suche, eine Textsuche oder eine reine Postleitzahlensuche ausführt, das Vorgehen zur Authentifizierung ist dabei immer gleich. Allein der Inhalt des Suchstrings ändert sich. PHP selbst ist keine streng typisierte Sprache, somit ist es egal ob $sSearchString eine Zeichenfolge oder eine Zahl ist. In anderen Programmiersprachen muss eine Postleitzahl, sollte sie als Integer oder ähnliches vorliegen, natürlich zunächst in einen String konvertiert werden.

Authentifizierung bei einer Wettervorhersage
Das Vorgehen beim Abfragen der Wetterdaten für einen Ort ist dem bei einer Suchanfrage sehr ähnlich. Der URL werden ein wetter.com city code, der Projektname und eine Checksumme als GET-Parameter mitgegeben. Stimmen diese Informationen mit den für das Projekt gespeicherten überein, ist die Anfrage zulässig.

Auch hier wieder ein Beispiel in PHP für den Zusammenbau einer Wettervorhersage URL. Projektname für dieses Beispiel ist "beispielprojekt", der API Key lautet "geheim" und die Wettervorhersage wird für den wetter.com city code "DE0001020" (Berlin) angefordert. Der Projektname sowie der API Key werden beim Anlegen eines Projekts festgelegt und können in den Projektinformationen eingesehen werden.

            <?php
            $sForecastUrl   = 'http://api.wetter.com/forecast/weather';
            $sProjectName   = 'beispielprojekt';
            $sApiKey        = 'geheim';
            $sCityCode      = 'DE0001020';

            // Generieren der Checksumme, muss für jeden City Code neu berechnet werden
            $sChecksum = md5($sProjectName . $sApiKey . $sCityCode);

            $sForecastUrl .= '/city/' . $sCityCode;
            $sForecastUrl .= '/project/' . $sProjectName;
            $sForecastUrl .= '/cs/' . $sChecksum;
            ?>
        

Am Ende des Scripts wäre $sSearchUrl gleich