Opencaching-API

Aus Opencaching-Wiki
Zur Navigation springen Zur Suche springen

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 inzwischen bei den Opencaching-Länderseiten in Polen, den USA, Großbritannien und den Niederlanden verfügbar. Eine Bereitstellung auf Opencaching.de[1] ist in Arbeit. Alternativ kann hier 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.pl/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:

  • Eventcaches können nicht geloggt werden (in Arbeit)
  • es können keine Logbilder hochgeladen werden
  • Attribute werden bislang nicht als eigene Datenfelder, sondern nur als Textanhang in der Cachebeschreibung mitgeliefert, auch in GPX-Dateien. (in Arbeit)

Außerdem sind gespeicherte Suchen aus dem Benutzerprofil nicht nutzbar. Dies ist technisch schwer zu realisieren und wird vermutlich nicht eingebaut. OKAPI-Anwendungen können dieses Feature mittels OKAPI-Suchfunktionen nachbilden.

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:

Logtext-Format

Im Zuge der OKAPI-Anpassung an Opencaching.de wurde die Behandlung von Logtexten beim Hochladen von Logs (submit) geändert. 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 aus hochgeladenen Logtexten entfernt.

weitere Informationen zum OKAPI-Log-Format

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 (Namespace gsak: ergänzt). Falls ein OKAPI-Cient sich auf das fehlerhafte 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 neue Features

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

  • Logbilder können abgerufen 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

Weitere Ergänzungen sind in Arbeit.

Anmerkungen

  1. Opencaching.de schließt auch die italienische Seite Opencaching.it und die spanische Opencachingspain.es mit ein; alle laufen auf dem gleichen Server.