Opencaching-API: Unterschied zwischen den Versionen
| Zeile 24: | Zeile 24: | ||
=== Logtext-Format === | === 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 | 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 [http://www.opencaching.pl/okapi/services/logs/submit.html#arg_comment_format 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. | Auf keinen Fall sollte "plain text" ''ohne'' Angabe von ''comment_format=plaintext'' hochgeladen werden - der Text könnte verstümmelt werden. | ||
| Zeile 33: | Zeile 33: | ||
===Lizenz-Disclaimer=== | ===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 [http://www.opencaching. | 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 [http://www.opencaching.pl/okapi/services/caches/geocache.html#arg_attribution_append attribution_append=none] kann dies abgeschaltet werden. Stattdessen muss dann das Feld ''attribution_note'' angefordert und dessen Inhalt wiedergegeben bzw. mitgeliefert werden. | ||
== Anmerkungen == | == Anmerkungen == | ||
Version vom 4. April 2013, 21:47 Uhr
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
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.