Opencaching-API

Die Opencaching-API (kurz: OKAPI) ist eine moderne Programmierschnittstelle, mit der Cache-, und Log- und Benutzerdaten von Opencaching-Seiten abgerufen werden können. Außerdem ist das Hochladen von Logs möglich. Dadurch lassen sich z.B. Smartphone-Apps mit Field-Logging-Funktion anbieten. Auch das Replizieren einer kompletten Opencaching-Datenbank ist möglich.

Weitere Funktionen sind das Beobachten und Ignorieren vom Caches; dabei wird auf die entsprechenden Listen im Benutzerprofil zugegriffen.

Die OKAPI ist bei den Opencaching-Länderseiten in Deutschland/Italien/Spanien, Polen, den USA, Großbritannien und den Niederlanden verfügbar. Auf Opencaching.de kann alternativ auch die weniger leistungsfähige XML-Schnittstelle genutzt werden.

Funktionsweise

Die OKAPI stellt verschiedene Webservices zur Verfügung, die Daten wahlweise im JSON- oder XML-Format liefern. Außerdem ist der Download von Cachedaten im GPX-Format möglich. Eine Beschreibung aller angebotenen Funktionen gibt es auf opencaching.de/okapi.

Entwicklung

Die OKAPI wurde vom dem polnischen Geocacher Wojciech Rygielski (Wrygiel) entwickelt, der auch für die Weiterführung des Projekts verantwortlich ist. Die Entwicklung wird zentral auf Google Code koordiniert; von dort werden Code-Updates auf die einzelnen Länderseiten verteilt.

Einschränkungen

Gegenüber der üblichen Opencaching.de-Funktionalität hat die OKAPI einige Einschränkungen:

Attribute werden bislang nur als Textliste statt einzelne Felder mit wohldefinierten IDs mitgeliefert, auch in GPX-Dateien. (in Arbeit)
es können keine Logbilder hochgeladen werden
gesperrte Caches können nicht abgerufen werden (Info)
gespeicherte Suchen aus dem Benutzerprofil sind nicht nutzbar
GC- und NC-Wegpunkte von Mehrfachlistings sind nicht abfragbar

Anpassung bestehender OKAPI-Clients an Opencaching.de

Grundsätzlich sind alle bestehenden OKAPI-Anwendungen auch mit Opencaching.de funktionsfähig. Die Beachtung der folgenden Punkte kann aber hilfreich sein:

Cachetypen

Die OKAPI dokumentiert bislang nur die Cachetypen "Traditional", "Multi", "Quiz", "Virtual" und "Event". Auf Opencaching.de gibt es fünf weitere Typen, die in der OKAPI (geocache.type) wie folgt heißen:

Webcam
Moving
Math/Physics
Drive-In
Other

Der Typ Math/Physics wird wahrscheinlich nicht mehr lange verwendet und sollte als "Quiz" behandelt werden.

Logtext-Format

Im Zuge der OKAPI-Anpassung an Opencaching.de wurde die Behandlung von Logtexten beim Hochladen von Logs (submit) verbessert. Früher war das Format undefiniert – es konnte "plain text" oder HTML sein, und die Weiterverarbeitung hing von der jeweiligen Opencaching-Seite ab. Nun gibt es einen neuen Parameter comment_format, mit dem das Format ausdrücklich angegeben werden kann und sollte.

Auf keinen Fall sollte "plain text" ohne Angabe von comment_format=plaintext hochgeladen werden - der Text könnte verstümmelt werden.

Unabhängig hiervon ist zu beachten, dass die Software unerlaubte HTML-Tags und -Attribute aus hochgeladenen Logtexten entfernt. Dies ist auf verschiedenen Opencaching-Seiten unterschiedlich gelöst; die gleichen Tags können also auf einer Seite erlaubt sein und auf einer anderen nicht. Zudem haben die HTML-Purifier auf allen Opencaching-Seiten Bugs und filtern u.U. auch erlaubte Tags oder Attribute weg.

→ weitere Informationen hierzu im OKAPI-Projekt

Log-Uhrzeiten

Ebenfalls in Zusammenhang mit der Anpassung an Opencaching.de wurde die Bedeutung der Log-Uhrzeit klarer definiert (service/logs/entry, date-Feld). Wenn die Zeit gleich 00:00:00 ist, ist davon auszugehen, dass das Log ohne Uhrzeit eingegeben wurde und nicht etwa um 0:00 Uhr geloggt. Bei Werten ungleich 00:00:00 ist eine Uhrzeitanzeige sinnvoll.

→ weitere Informationen hierzu im OKAPI-Projekt

GPX-Child-Waypoints

Die Implementation für die GSAK-Erweiterung im GPX-Format wurde korrigiert; zusätzliche Wegpunkte werden nun so gekennzeichnet wie von GSAK vorgesehen (mit Namespace gsak:). Falls ein OKAPI-Cient sich auf das alte Format verlassen hat, muss er angepasst werden.

Lizenz-Disclaimer

Die OKAPI hängt standardmäßig einen Disclaimer an alle abgerufenen Cachebeschreibungen an, der den Datenlizenz-Anforderungen der jeweiligen Opencaching-Website entspricht. Über die neue Option attribution_append=none kann dies abgeschaltet werden. Stattdessen muss dann das Feld attribution_note angefordert und dessen Inhalt wiedergegeben bzw. mitgeliefert werden.

→ weitere Informationen hierzu im OKAPI-Projekt

Weitere neue Features

Für den OKAPI-Start auf Opencaching.de wurden noch einige weitere neue Funktionen eingebaut:

Logbilder können abgerufen werden
Event-Caches können geloggt werden
die geschätzte Zeit und Wegstrecke für einen Cache können abgerufen werden, wenn im Listing vorhanden
das Vorschaubild eines Caches ist abrufbar
die neue GPX-Option "images=descrefs:thumblinks" bettet verlinkte Thumbnail-Bilder in GPX-Daten ein

Weitere Ergänzungen sind in Arbeit.