Opencaching-API: Unterschied zwischen den Versionen
Link zum Forum aktualisiert
(+kat) |
(Link zum Forum aktualisiert) |
||
(48 dazwischenliegende Versionen von 2 Benutzern werden nicht angezeigt) | |||
Zeile 1: | Zeile 1: | ||
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 [[Log]]s möglich. Dadurch lassen sich z.B. [[Smartphone-Caching|Smartphone-Apps]] mit [[Fachjargon#Field Logging |Field-Logging]]-Funktion anbieten. Auch das Replizieren einer kompletten Opencaching-Datenbank ist möglich. | 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 [[Log]]s möglich. Dadurch lassen sich z.B. [[Smartphone-Caching|Smartphone-Apps]] mit [[Fachjargon#Field Logging|Field-Logging]]-Funktion anbieten. Auch das Replizieren einer kompletten Opencaching-Datenbank ist möglich. | ||
Die OKAPI ist | Weitere Funktionen sind das [[Caches beobachten|Beobachten]] und [[Caches ignorieren|Ignorieren]] vom Caches; dabei wird auf die entsprechenden Listen im Benutzerprofil zugegriffen. | ||
Die OKAPI ist bei den [[Opencaching|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. | |||
Es gibt bereits einige [[OKAPI-Clients]] für Opencaching.de. | |||
== Funktionsweise == | == Funktionsweise == | ||
Die OKAPI stellt [http://www.json.org/ JSON]- | Die OKAPI stellt verschiedene Webservices zur Verfügung, die Daten wahlweise im [http://www.json.org/ JSON]- oder XML-Format liefern. Außerdem ist der Download von Cachedaten im [[GPX-Datei|GPX-Format]] möglich. Eine Beschreibung aller angebotenen Funktionen gibt es auf '''[http://www.opencaching.de/okapi/ opencaching.de/okapi]'''. | ||
== Zugriff auf das Benutzerkonto == | |||
Wenn eine OKAPI-Anwendung deine Funde oder Nichtfunde anzeigen, auf deine [[Caches beobachten|Beobachtungs-]] oder [[Caches ignorieren|Ignorierliste]] zugreifen soll oder Caches [[Das Onlinelog|loggen]] soll, musst du ihr Zugriff auf dein [[Benutzerprofil|Benutzerkonto]] gewähren. Dies geht halbautomatisch innerhalb der Anwendung: Du wirst bei Bedarf gefragt, ob du den Zugriff gewähren möchtest. | |||
Mit dem Menüpunkt [http://www.opencaching.de/okapi/apps/ API-Anwendung] unter „Mein Profil“ kannst du sehen, welchen Anwendungen du Zugriff gegeben hast, und kannst dies jeweils widerrufen. | |||
== Entwicklung == | == Entwicklung == | ||
Die OKAPI wurde vom dem polnischen Geocacher Wojciech Rygielski ([http://forum. | Die OKAPI wurde vom dem polnischen Geocacher Wojciech Rygielski ([http://forum.opencaching.de/index.php?action=profile;u=410 Wrygiel]) entwickelt, der auch für die Weiterführung des Projekts verantwortlich ist. Die Entwicklung wird zentral auf [http://code.google.com/p/opencaching-api/ Google Code] koordiniert; von dort werden Code-Updates auf die einzelnen Länderseiten verteilt. | ||
Die OKAPI-Entwicklung ist offen für jeden, der etwas beitragen möchte. Wenn bestimmte Features für eine Anwendung fehlen kann man also versuchen, sie selbst einzubauen. | |||
== Einschränkungen == | |||
Gegenüber der üblichen Opencaching.de-Funktionalität hat die OKAPI einige Einschränkungen: | |||
* es können keine Logbilder hochgeladen werden | |||
* es können keine Status(änderungen) geloggt werden | |||
* gesperrte Caches können nicht abgerufen werden ([http://code.google.com/p/opencaching-api/issues/detail?id=123 Info]) | |||
* gespeicherte Suchen aus dem Benutzerprofil sind nicht nutzbar | |||
== 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 kann als "Quiz" dargestellt werden. | |||
''Achtung:'' Suchabfragen nach diesen Cachetypen auf anderen OC-Seiten als Opencaching.de/.it/.es führen zu einer OKAPI-Fehlermeldung. Bei der Suche muss also die gewählte OC-Seite mit berücksichtigt 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 [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. | |||
Unabhängig hiervon ist zu beachten, dass die Software [http://www.opencaching.de/articles.php?page=htmltags 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. | |||
→ [http://code.google.com/p/opencaching-api/issues/detail?&id=124 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. | |||
→ [http://code.google.com/p/opencaching-api/issues/detail?&id=209 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 [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. | |||
→ [http://code.google.com/p/opencaching-api/issues/detail?id=178 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 [[Vorschaubilder|Vorschaubild]] eines Caches ist abrufbar | |||
* die neue GPX-Option "images=descrefs:thumblinks" bettet verlinkte Thumbnail-Bilder in GPX-Daten ein | |||
* GC-Codes von [[Mehrfachlisting]]s sind abfragbar | |||
* Es wurden globale, mit eigenen IDs („A-Codes“) identifizierte Attribute eingeführt. | |||
* [[Schutzgebiete]], in denen Geocaches sich wahrscheinlich befinden, sind abfragbar | |||
[[Kategorie:Geocaching-Software]] | [[Kategorie:Geocaching-Software]] |