Dokumentation Opencaching XML-Interface

Das XML-Interface dient zum automatisierten abfragen aller Caches, Logeinträge, Benutzer und/oder Bilder. Dieses Interface ist nicht für Endbenutzer gedacht, sondern für Anwendungs-Entwickler. Alternativ steht die modernere Opencaching-API (OKAPI) zur Verfügung.

Die abgerufenen Daten sind urheberrechtlich geschützt und dürfen nur unter den Bedingungen der Opencaching.de-Datenlizenz weitergegeben und genutzt werden.

The XML interface allows automatic download of cache, logs, user and/or pictures data. It is not made for end-users but for application developers. There also is the more modern OKAPI interface.
This documentation is currently available in German only. If you need english text, please contact us at kontakt@opencaching.de and tell us about the application you are going to develop; then we may translate it.
The downloaded data is copyrighted and must only be used under the terms of Opencaching.de data license.

Version 1.1

Diese Version wurde ca. 2007 veröffenlicht.

Änderungen in Version 1.2 (Februar 2013)

neues Attribut ispublishdate bei cache.datecreated
Ausgabe von Nano-Cachgrößen

Seit dem 7. April 2013 gibt es folgende Ergänzung:

Wenn beim Auruf der zusätzliche Parameter "&license=1" angegeben ist, wird bei Cachebeschreibungen, Logs und Bildern ein zusätzliches Feld <license>...</license> mitgeliefert, das einen Copyright-Disclaimer gemäß Datenlizenz enthält. Dieser ist bei der Darstellung der Daten mit anzuzeigen und bei Weitergabe mitzuliefern. Wenn der license-Parameter nicht angegeben ist, wird der Disclaimer automatisch an alle Cachebeschreibungen angehängt.
Mit dem zusätzlichen Parameter "language" kann die Sprache des Disclaimers gewählt werden, z. B. "&language=de" für Deutsch. Ist "language" nicht angegeben, wird der Text nach Möglichkeit in der Sprache der Cachebeschreibung bzw. des Logeintrags erzeugt, ansonsten in Englisch.

Änderungen in Version 1.3 (Mai 2013)

Zusätzliche Wegpunkte von Caches werden nun in einer <wpts>...</wpts>-Liste mitgeliefert.
Das <date>-Element von Logs enthält nun auch die Uhrzeit. 00:00:00 bedeutet, dass keine Uhrzeit geloggt wurde; alles andere bedeutet, dass mit Stunde und Minute geloggt wurde.
Element für Bildeigenschaften von <attributes> in <picattr> umbenannt, um Kollisionen mit dem Cache-Attribut-Element zu vermeiden.
Vorschaubild-Flag (preview) zu <picattr> hinzugefügt.
zusätzliche Logtypen 9 (archiviert), 10 (kann gesucht werden), 11 (momentan nicht verfügbar) und 13 (gesperrt); Ausgabe als Typ 3 (Hinweis) in älteren XML-Versionen
teamcomment-Flag zum <logtype> hinzugefügt

Änderungen in Version 1.4 (Juni 2013)

Bei Caches wird zusätzlich das Feld listing_lastmodified ausgegeben, das das Gesamt-Änderungsdatum des Listings inklusive hinzugefügten/geänderten/gelöschten Beschreibungen und Bildern enthält. Bei Logs gibt es entsprechend das zusätzliche Feld log_last_modified, das Bilder mit einschließt. Das heißt: Ab Version 1.4 werden <cache>- und <cachelog>-Einträge auch dann neu übertragen, wenn es nur Änderungen bei Beschreibungen oder Bildern gab.
Wenn ein User einen Cache empfohlen und diesen mehrfach als "Fund" geloggt hat, wurde bislang bei allen Fundlogs recommended="1" mitgeliefert (allerdings nicht rückwirkend - das war ein Bug. Auch zurückgezogene Empfehlungen wurden nicht immer sofort ausgeliefert).
Dieses Verhalten wurde so geändert, dass recommended="1" nur noch bei genau dem Log mitgeliefert wird, mit dem die Empfehlung für den Cache gegeben wurde. Mehrfachempfehlungen sind nicht möglich (und waren es noch nie).
Gleichzeitig wurde auch die Darstellung auf opencaching.de geändert: Bei Mehrfach-Fundlogs erscheint der grüne Stern nur noch an einem der Logs.
Bei Anwendungen, die das recommended-Flag verwenden wird ein kompletter Neuabruf aller Logs per Version 1.4 empfohlen, weil die alten Daten fehlerhaft sein können. Außerdem sollte die Handhabung von Mehrfachlogs geprüft werden.

Ab Februar 2016 gibt es folgende Änderungen:

Navicache-Wegpunkte in OC-Listings werden nicht mehr unterstützt. Das caches-Attribut "nccom" enthält nun immer einen Leerstring.

Änderungen in Version 1.5 (März 2016)

nccom-Attribut entfernt
Bei Caches wird zusätzlich das Attribut gccom2 ausgegeben. Es enthält vom Opencaching-Team handgewartete GC-Wegpunkte.
Beim Cachestatus und beim Logtyp weden die zusätzlichen Attribute needs_maintenance und listing_oudated ausgegeben, also die logbaren Wartungszustände. Bei Caches hat es den Wert 0 (Cache ok) oder 1 (benötigt Wartung), bei Logs den Wert 0 (keine Angabe), 1 (Cache ok) oder 2 (benötigt Wartung).
Bei Bildern wird das zusätzliche Element <position> ausgegeben. Es enthält die Position des Bildes in der Liste der Bilder eines Caches oder Logs, beginnend mit 1.

Der XML-Doctype lautet in allen Versionen "oc11xml".

Ausgabeformat

Die Ausgabe ist eine oder mehrere xml,zip,gz oder bz2-Dateien. Es stehen 2 Übertragungsmodi bereit: in Paketen zu je 500 Datensätzen oder in einer Datei.

Die folgenden XML-Abschnitte stehen zur Verfügung. Sie werden immer in dieser Reihenfolge ausgegeben:

user (Benutzerdaten)
caches (Caches)
cachedesc (Cachebeschreibungen)
cachelog (Logeinträge)
picture (Bilder)
removedobject (gelöschte Objekte)

Allgemeine XML-Elemente

lastmodified

Datum an dem dieser Datensatz zuletzt geändert wurde. Es werden keine Abhängigkeiten berücksichtigt. D.h. Wenn z.B. eine Cachebeschreibung geändert wird, ändert sich nur deren lastmodified, nicht jedoch das des Caches (hierfür gibt es das separate Feld listing_last_modified.) Datumsangaben sind immer in der Form "yyyy-mm-dd hh:mm:ss" oder "yyyy-mm-dd"

datecreated

Datum an dem dieser Datensatz angelegt wurde.

id

Zu unterscheiden ist die id (identifier) und die uuid (universal unique identifier). Die id (Zahl) ist ein nur auf der jeweiligen Webseite gültiger identifier, während die uuid (alphanumerische Folge) auf jeder Seite die Opencaching-Daten verwendet gültig sein sollte. Beispiel: bei dem Datenabgleich von www.opencaching.de und devel.opencaching.de wird auf devel.opencaching.de eine neue id für den Datensatz erzeugt und die uuid beibhalten.

Attributliste

user (Benutzerdaten)

username

Benutzername

pmr

1: Der Benutzer hat angegeben ein PMR-Funkgerät auf Kanal 2 mit auf Tour zu nehmen.
0: Keine Angabe

cache (Caches)

lastmodified ist das letzte Änderungsdatum des cache-Datensatzes, ohne Änderungen an Cachebeschreibungen oder Bildern. Das Gesamt-Änderungsdatum steht im Feld listing_lastmodified.

datecreated ist bei mit OC Version 1 und 2 angelegten Caches das Datum, an dem das Listing angelegt wurde, bei mit Version 3 angelegten Caches das Veröffentlichungsdatum. Ab Interface Version 1.2 zeigt das Attribut ispublishdate="1" an, dass es sich um das Veröffentlichungsdatum handelt.

Ab XML-Version 1.2 werden im size-Feld auch Nano-Größen zurückgeliefert. In älteren Interface-Versionen wird stattdessen "micro" ausgegeben.

Es fehlen noch Empfehlungen und zusätzliche Wegpunkte; wird bei Bedarf eingebaut.

cachedesc (Cachebeschreibungen)

<cachedesc>
<id id="5697">9BA489ED-AC62-B26D-6EC8-4D52DF3CD008&</id>
<cacheid id="4927">AB551E31-8633-0CD1-26AD-324355D4E920</cacheid>
<language id="EN"><![CDATA[Englisch]]></language>
<shortdesc><![CDATA[Drive-In-Cache especially for motorcyclists]]></shortdesc>
<desc html="1"><![CDATA[This MoCache is intended to connect the MoCache series to other
motorcycle-friendly caches on The Alb. Furthermore this great road
between Erpfingen and Undingen was really worth it... <br />
<br />
<a href="http://people.freenet.de/6x7/mocaches.html">Other MoCaches</a>
]]></desc>
<hint><![CDATA[guard rail pole]]></hint>
<lastmodified>2005-12-24 14:38:13</lastmodified>
</cachedesc>

cachelog (Logeinträge)

<cachelog>
<id id="13037">F0DAC335-0FA6-3479-45AF-03E2F6BC28B9</id>
<cacheid id="3439">048A8BF3-AA75-0741-CF60-6FBAE239EE11</cacheid>
<user id="113" uuid="CAA9E3C5-50DF-4E9E-191F-CECABA6A8A19"><![CDATA[Team Schnitzeljagd]]></user>
<logtype id="1" recommended="0" teamcomment="0" needs_maintenance="0" listing_outdated="0"><![CDATA[Gefunden]]></type>
<date>2005-05-18 16:20:00</date>
<text><![CDATA[Gut gefunden.<br />
Grüße von<br />
Volker]]></text>
<datecreated>2005-12-24 06:24:07</datecreated>
<lastmodified>2005-12-24 06:24:07</lastmodified>
<log_lastmodified>2005-12-24 06:41:30</log_lastmodified>
</cachelog>

lastmodified ist das letzte Änderungsdatum des Log-Datensatzes, ohne Änderungen an Bildern. Das Gesamt-Änderungsdatum steht im Feld log_lastmodified.

picture (Bilder)

<picture>
<id id="4619">558990D1-4DE2-50AF-B53A-135E87704D70</id>
<url>https://www.opencaching.de/images/uploads/558990D1-4DE2-50AF-B53A-135E87704D70.jpg</url>
<title><![CDATA[Schlurfende Gestalten]]></title>
<desc html="0"></desc>
<object id="73240" type="1" typename= "cachelog">4FE4B999-315D-43C1-11C2-2B81E68168CD</object>
<picattr spoiler="0" display="1" preview="0" />
<datecreated>2005-12-24 01:01:38</datecreated>
<lastmodified>2005-12-24 01:01:38</lastmodified>
<position>1</position>
</picture>

removedobject (gelöschte Objekte)

Datenauswahl

Die Auswahl erfolgt zum einen durch den Paramter modifiedsince, mit dem inkrementelle Updates gesteuert werden, zum anderen über eine Gebietsauswahl.

Zu übertragende Daten auswählen

Folgende Parameter stehen zur Verfügung um die zu übertragenden Daten auszuwählen.

Die Werte dürfen 1 oder 0 sein, Default ist 0.
0=Datensätze nicht übertragen
1=Datensätze übertragen

user
cache
cachedesc
cachelog
picture
removedobject

modifiedsince

Alle Datensätz übertragen, die nach diesem Datum angelegt oder modifiziert wurden. Das Datumsformat ist yyyymmddhhnnss

Gebietsauswahl

Es muss keine Gebietsauswahl getroffen werden. Eine Kombination von Land, Koordinaten oder cacheid ist nicht möglich.

Nach Land

Parameter country ... wird dieser Parameter angegeben, werden nur Datensätze übertragen, die mit Caches in Zusammenhang stehen, die in diesem Land versteckt wurden. User-Records werden nicht übertragen, removedobjects werden alle übetragen.

Für Bilder muss dabei angegeben werden, ob nur Bilder übertragen werden die von Caches stammen oder auch von Cachelogs:
Paramter: picturefromcachelog = 0/1, default 0

Nach Koordinaten

Parameter lat, lon, distance ... werden diese Parameter angegeben, werden nur Datensätz übertragen, die mit Caches in Zusammenhang stehen, die in diesem Gebiet versteckt wurden. User-Records werden nicht übertragen, removedobjects werden alle übetragen.

Nach cacheid

Parameter cacheid ... wird dieser Parameter angegeben, werden nur Datensätz übertragen, die mit Cache in Zusammenhang stehen. User-Records werden nicht übertragen, removedobjects werden alle übetragen.

Für Bilder muss dabei angegeben werden, ob nur Bilder übertragen werden die von Caches stammen oder auch von Cachelogs:
Paramter: picturefromcachelog = 0/1, default 0

Nach Wegpunkt

Paramter wp ... wie cacheid, ausser dass statt der cacheid der Opencaching Wegpunkt verwendet wird.

Nach uuid

Paramter uuid ... wie cacheid, ausser dass statt der cacheid die UUID des Caches verwendet wird.

Beispiele

1. Alle Daten inkrementell abrufen
https://www.opencaching.de/xml/ocxml15.php?modifiedsince=<date>&user=1&cache=1&cachedesc=1&cachelog=1&picture=1&removedobject=1

2. Alle Daten von Deutschland inkrementell abrufen
https://www.opencaching.de/xml/ocxml15.php?modifiedsince=<date>&cache=1&cachedesc=1&cachelog=1&picture=1&removedobject=0&country=DE&picturefromcachelog=1

3. Alle Caches ohne Logs von Deutschland inkrementell abrufen
https://www.opencaching.de/xml/ocxml15.php?modifiedsince=<date>&cache=1&cachedesc=1&picture=1&removedobject=0&country=DE

4. Alle Daten im Umkreis von 15 km abrufen
https://www.opencaching.de/xml/ocxml15.php?modifiedsince=<date>&cache=1&cachedesc=1&cachelog=1&picture=1&removedobject=0&lat=48&lon=9&distance=15&picturefromcachelog=1

5. Alle Bilder abrufen
https://www.opencaching.de/xml/ocxml15.php?modifiedsince=<date>&picture=1

6. Alle Bilder von Caches abrufen die in Deutschland versteckt sind
https://www.opencaching.de/xml/ocxml2.php?modifiedsince=<date>&picture=1&country=DE

7. Alle Bilder von Caches und deren Logs abrufen die in Deutschland versteckt sind
https://www.opencaching.de/xml/ocxml15.php?modifiedsince=<date>&picture=1&country=DE&picturefromcachelog=1

Mit ocxml11.php kann stattdessen die Interface-Version 1.1 verwendet werden.

Diese Anfragen werden mit einem kurzen XML-Stream beantwortet, der die XML-Session-Id zurückgibt. Mit dieser Id können dann die Daten abgerufen werden.

<?xml version="1.0"?>
<ocxmlsession>
<sessionid>12345</sessionid>
<records user="193" cache="211" cachedesc="235" cachelog="439" picture="108" removeobject="19" />
</ocxmlsession>

Die Anzahl der Datensätz muss nicht exakt mit den übertragenen übereinstimmen - mehr Datensätze werden jedoch auf keinen Fall übertragen. Die Summe der Datensätze ist in diesem Beispiel 1205 - es werden also 3 Aufrufe benötigt (500, 500, 205 Datensätze).

Die Daten können dann mit folgender Anfrage abgerufen werden:
https://www.opencaching.de/xml/ocxml15.php?sessionid=12345&file=1
https://www.opencaching.de/xml/ocxml15.php?sessionid=12345&file=2
https://www.opencaching.de/xml/ocxml15.php?sessionid=12345&file=3

Die Sessionid ist eine Stunde lang gültig, wobei sich dieser Zeitraum mit jedem einzelnen Dateiabruf verlängert – zwischen den Einzelabrufen darf also maximal eine Stunde vergehen. Dauert es länger, müsste eine neue sessionid angefordert werden.

Alle Ergebnisse mit einem Aufruf abfragen

Um alle Ergebnisse in einer Datei abzurufen muss bei dem Aufruf der Paramter session auf 0 gesetzt werden.

Beispeil:
https://www.opencaching.de/xml/ocxml15.php?modifiedsince=<date>&user=1&cache=1&cachedesc=1&cachelog=1&picture=1&removedobject=1&session=0

Dateikomprimierung einstellen

Dei Dateikomprimierung kann mit dem Paramter zip eingestellt weren. Mögliche Werte sind 0, zip, bzip2, gzip. Null bedeutet hier keine Kompression. Wird keine Kompression angegeben, wird zip verwendet.

Beispeil:
https://www.opencaching.de/xml/ocxml15.php?modifiedsince=<date>&user=1&cache=1&cachedesc=1&cachelog=1&picture=1&removedobject=1&session=0&zip=bzip2
https://www.opencaching.de/xml/ocxml15.php?sessionid=12345&file=1&zip=gzip

XML-Optionen

Die folgenden XML-Optionen müssen bei jedem Aufruf übergeben werden.

xmldecl ... 0 = keine Xml-Deklaration / (Default) 1=Xml-Deklaration
doctype ... 0 = keine Xml-Document-Type-Definition / (Default) 1=Xml-Document-Type-Definition
ocxmltag ... 0 = kein oc11xml-Tag zu Beginn / (Default) 1=oc11xml-Tag zu Beginn
cdata ... 0=XML-Steuerzeichen in Texten maskieren (z.B. & => &) / (Default) 1=Texte in CDATA-Abschnitte einfassen
charset ... (Default) iso-8859-1 / utf-8
attrlist ... (Default) 0 = keine Attributliste übertragen / 1 = Attributliste übertragen

Beispiele

https://www.opencaching.de/xml/ocxml15.php?modifiedsince=20060320000000&user=1&cache=1&cachelog=1&cachedesc=1&picture=1&removedobject=1&session=1&charset=utf-8&cdata=1&xmldecl=0&ocxmltag=0&doctype=0
https://www.opencaching.de/xml/ocxml15.php?sessionid=4711&file=1&charset=utf-8&cdata=1&xmldecl=0&ocxmltag=0&doctype=0

Sonstige Anmerkungen

Für den ersten Aufruf des Interface muss als modifiedsince das Datum 1.8.2005 um 00:00:00 Uhr angegeben werden. Es gibt keine Datensätze die vor diesem Datum angelegt wurden.
Um Probleme wegen Differenzen der Uhrzeit zwischen Client und Server zu umgehen, muss für den nächsten Inkrementellen Abruf der Daten das Datum um Kopf der XML-Datei minus 1 Sekunde angeben werden:

<?xml version="1.0" encoding="iso-8859-1" standalone="no" ?>
<!DOCTYPE oc11xml...>
<oc11xml version="1.2" date="2006-03-10 18:37:34" since="2006-03-08 22:02:42">
Zeitverschiebungen / unterschiedliche Zeitzonen zwischen Client und Server werden nicht unterstützt.

Ressourcen

Das XML-Dokument enthält folgende DTD (Document Type Definition): https://www.opencaching.de/xml/ocxmlXX.dtd mit XX = Versionummer, z.B. ocxml12.dtd für Version 1.2.
Der Quellcode ist hier erhältlich: https://github.com/OpencachingDeutschland/oc-server3/tree/stable/htdocs/xml
Eine Referenzimplementierung kann hier heruntergeladen werden: https://github.com/OpencachingDeutschland/oc-server3/tree/stable/local/ocxml11client
Fragen zum Interface können im Opencaching-Forum gestellt werden: http://forum.opencaching.de/

Lizenz:

Der Quellcode steht unter der GNU Gerneral Public License Version 2 und später, siehe https://github.com/OpencachingDeutschland/oc-server3/tree/stable/doc/license.txt.
Für Daten, die über das XML-Interface abgerufen werden, gelten die Nutzungsbedingungen von Opencaching.de: https://www.opencaching.de/articles.php?page=impressum#tos