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)

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

Änderungen in Version 1.3 (Mai 2013)

Änderungen in Version 1.4 (Juni 2013)

Ab Februar 2016 gibt es folgende Änderungen:

Änderungen in Version 1.5 (März 2016)

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:

  1. user (Benutzerdaten)
  2. caches (Caches)
  3. cachedesc (Cachebeschreibungen)
  4. cachelog (Logeinträge)
  5. picture (Bilder)
  6. 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

<attrlist>
  <attr id="1" icon_large="http://www.opencaching.de/images/attributes/night.gif"
          icon_no="http://www.opencaching.de/images/attributes/night-no.gif"
          icon_undef="http://www.opencaching.de/images/attributes/night-undef.gif">
                <![CDATA[Nachtcache]]>
  </attr>
  <attr id="6" icon_large="http://www.opencaching.de/images/attributes/oconly.gif"
          icon_no="http://www.opencaching.de/images/attributes/oconly-no.gif"
          icon_undef="http://www.opencaching.de/images/attributes/oconly-undef.gif">
                <![CDATA[Nur bei Opencaching]]>
  </attr>
  <attr id="7" icon_large="http://www.opencaching.de/images/attributes/wwwlink.gif"
          icon_no="http://www.opencaching.de/images/attributes/wwwlink-no.gif"
          icon_undef="http://www.opencaching.de/images/attributes/wwwlink-undef.gif">
                <![CDATA[Nur Hyperlink]]>
  </attr>
  <attr id="8" icon_large="http://www.opencaching.de/images/attributes/letterbox.gif"
          icon_no="http://www.opencaching.de/images/attributes/letterbox-no.gif"
          icon_undef="http://www.opencaching.de/images/attributes/letterbox-undef.gif">
                <![CDATA[Letterbox (benötigt Stempel)]]>
  </attr>
</attrlist>

user (Benutzerdaten)

<user>
  <id id="12345">4CE405E5-C110-CE00-9E88-8907F2212C73</id>
  <username><![CDATA[Joe Geocacher]]></username>
  <pmr>0</pmr>
  <datecreated>2005-12-24 11:22:34</datecreated>
  <lastmodified>2005-12-29 15:38:01</lastmodified>
</user>

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)

<cache>
  <id id="270">D455C916-7737-8210-F7FF-C6872E561CEB</id>
  <user id="113" uuid= "CAA9E3C5-50DF-4E9E-191F-CECABA6A8A19"><![CDATA[TeamSchnitzeljagd]]></user>
  <name><![CDATA[Pegeluhr]]></name>
  <longitude>8.45058</longitude>
  <latitude>49.46393</latitude>
  <type id="2" short="Trad."><![CDATA[normaler Cache]]></type>
  <status id="2" needs_maintenance="0" listing_outdated="0"><![CDATA[Momentan nicht verfügbar]]></status>
  <country id="DE"><![CDATA[Deutschland]]></country>
  <size id="2"><![CDATA[mikro]]></size>
  <desclanguages>DE</desclanguages>
  <difficulty>4</difficulty>
  <terrain>2</terrain>
  <rating waylength="1.5" needtime= "0.5"></rating>
  <waypoints gccom= "" gccom2="" oc="OCR2D2"></waypoints>
  <datehidden>2005-08-01</datehidden>
  <datecreated ispublishdate="0">2005-09-08 15:45:02</datecreated>
  <lastmodified>2005-12-20 20:58:41</lastmodified>
  <listing_lastmodified>2006-04-13 16:31:58</listing_lastmodified>
  <attributes>
    <attribute id="6"><![CDATA[Nur bei Opencaching]]></attribute>
  </attributes>
  <wpts>
    <wpt id="25" type="1" typename="Parking" longitude="8.01667" latitude="50.00000"><![CDATA[Parkplatz, von hier 1 km Fußweg]]></wpt>
    <wpt id="26" type="2" typename="Stage or reference point" longitude="8.02333" latitude="50.01544"><![CDATA[Station 1]]></wpt>
  </wpts>
</cache>

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... &lt;br /&gt;
  &lt;br /&gt;
  &lt;a href=&quot;http://people.freenet.de/6x7/mocaches.html&quot;&gt;Other MoCaches</a&gt;
  ]]></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.&lt;br /&gt;
Gr&uuml;&szlig;e von&lt;br /&gt;
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>http://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)

<removedobject>
  <id id="748" />
  <object id="2388" type="6" typename="picture">3C5A2147-BC21-CC96-B240-E3BEA829D936</object>
  <removeddate>2005-12-24 15:11:23</removeddate>
</removedobject>

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

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
http://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
http://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
http://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
http://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
http://www.opencaching.de/xml/ocxml15.php?modifiedsince=<date>&picture=1

6. Alle Bilder von Caches abrufen die in Deutschland versteckt sind
http://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
http://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:
http://www.opencaching.de/xml/ocxml15.php?sessionid=12345&file=1
http://www.opencaching.de/xml/ocxml15.php?sessionid=12345&file=2
http://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:
http://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:
http://www.opencaching.de/xml/ocxml15.php?modifiedsince=<date>&user=1&cache=1&cachedesc=1&cachelog=1&picture=1&removedobject=1&session=0&zip=bzip2
http://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. & => &amp;) / (Default) 1=Texte in CDATA-Abschnitte einfassen
charset ... (Default) iso-8859-1 / utf-8
attrlist ... (Default) 0 = keine Attributliste übertragen / 1 = Attributliste übertragen

Beispiele

http://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
http://www.opencaching.de/xml/ocxml15.php?sessionid=4711&file=1&charset=utf-8&cdata=1&xmldecl=0&ocxmltag=0&doctype=0

Sonstige Anmerkungen

Ressourcen

Lizenz: