Opencaching-API: Unterschied zwischen den Versionen

Aus Opencaching-Wiki
Zur Navigation springen Zur Suche springen
(Link zum Forum aktualisiert)
 
(38 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.


Weitere Funktionen sind das [[Caches beobachten|Beobachten]] und [[Caches ignorieren|Ignorieren]] vom Caches; dabei wird auf die entsprechenden Listen im Benutzerprofil zugegriffe.
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 inzwischen bei den [[Opencaching|Opencaching-Länderseiten]] in Polen, den USA, Großbritannien und den Niederlanden verfügbar. Eine Bereitstellung auf Opencaching.de<ref name="it_es"/> ist in Arbeit. Alternativ kann hier auch die weniger leistungsfähige [[XML-Schnittstelle]] genutzt werden.
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 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.pl/okapi/ opencaching.pl/okapi].
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.geocaching-network.com/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 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 ==
== Einschränkungen ==
Gegenüber der üblichen Opencaching.de-Funktionalität hat die OKAPI einige 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
* es können keine Logbilder hochgeladen werden
* Attribute sind bislang nur eingeschränkt nutzbar, weil es noch keine eindeutigen Attribut-Kennzeichnungen gibt. (in Arbeit)
* es können keine Status(änderungen) geloggt werden
* Zeitaufwand und Wegstrecke eines Caches sind nicht abfragbar (in Arbeit)
* 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


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:


== Anpassung bestehender OKAPI-Clients an Opencaching.de ==
=== Cachetypen ===
Grundsätzlich sind alle bestehenden OKAPI-Anwendungen auch mit Opencaching.de funktionsfähig. Im Zuge der OKAPI-Anpassung an Opencaching.de musste allerdings die Behandlung von Logtexten beim Hochladen von Logs (''submit'') geändert werden: Während sie früher je nach Installation teils als reiner Text (''plain text'') und teils als HTML verarbeitet wurden, sollte das Textformat nun explizit mit dem neuen Parameter ''comment_format'' angegeben werden. Ohne Angabe von ''comment_format'' wird der Text immer als HTML behandelt.
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]


Clients, die sich nach der früheren OKAPI-Dokumentation bzw. der OKAPI-Installation auf [http://www.opencaching.nl/ Opencaching.nl] gerichtet haben und ''plain text'' senden, sollten daher angepasst werden und zusätzlich ''comment_format=plaintext'' angeben. Andernfalls könnten Logtexte verstümmelt werden, die spezielle HTML-Zeichen (<, & etc.) enthalten.
===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.


Unabhängig hiervon ist zu beachten, dass die Software [http://www.opencaching.de/articles.php?page=htmltags unerlaubte HTML-Tags] aus hochgeladenen Logtexten entfernt.
===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=124 weitere Informationen zum OKAPI-Log-Format]
→ [http://code.google.com/p/opencaching-api/issues/detail?id=178 weitere Informationen hierzu im OKAPI-Projekt]


== Anmerkungen ==
===Weitere neue Features===
<references>
Für den OKAPI-Start auf Opencaching.de wurden noch einige weitere neue Funktionen eingebaut:
<ref name="it_es">Opencaching.de schließt auch die italienische Seite Opencaching.it und die spanische Opencachingspain.es mit ein; alle laufen auf dem gleichen [[Technik|Server]].</ref>
* Logbilder können abgerufen werden
</references>
* 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:Opencaching]]
[[Kategorie:Geocaching-Software]]
[[Kategorie:Geocaching-Software]]

Aktuelle Version vom 9. September 2015, 07:51 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 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.

Es gibt bereits einige OKAPI-Clients für Opencaching.de.

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.

Zugriff auf das Benutzerkonto

Wenn eine OKAPI-Anwendung deine Funde oder Nichtfunde anzeigen, auf deine Beobachtungs- oder Ignorierliste zugreifen soll oder Caches loggen soll, musst du ihr Zugriff auf dein 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 API-Anwendung unter „Mein Profil“ kannst du sehen, welchen Anwendungen du Zugriff gegeben hast, und kannst dies jeweils widerrufen.

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.

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 (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 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
  • GC-Codes von Mehrfachlistings sind abfragbar
  • Es wurden globale, mit eigenen IDs („A-Codes“) identifizierte Attribute eingeführt.
  • Schutzgebiete, in denen Geocaches sich wahrscheinlich befinden, sind abfragbar