Dokumentation Opencaching XML-Interface Version 1.1

Das XML-Interface dient zum automatisierten abfragen aller Caches, Logeinträ, Benutzer und/oder Bilder. Dieses Interface ist nicht fübenutzer gedacht, sondern primäfüsite-Entwickler.

Ausgabeformat

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

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

1. user (Benutzerdaten)
2. caches (Caches)
3. cachedesc (Cachebeschreibungen)
4. cachelog (Logeinträ)
5. picture (Bilder)
6. removedobject (gelöte Objekte)

Allgemeine XML-Elemente

lastmodified

Datum an dem dieser Datensatz zuletzt geäert wurde. Es werden keine Abhäigkeiten berühtigt. D.h. Wenn eine Cachebeschreibung geäert wird, äert sich nur deren lastmodified, nicht jedoch das des Caches. 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ür identifier, wäend die uuid (alphanumerische Folge) auf jeder Seite die Opencaching-Daten verwendet güsein sollte. Beispiel: bei dem Datenabgleich von www.opencaching.de und devel.opencaching.de wird auf devel.opencaching.de eine neue id fü 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öt 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ä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"><![CDATA[Momentan nicht verfü]></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= "" nccom="" oc="OCR2D2"></waypoints>
  <datehidden>2005-08-01</datehidden>
  <datecreated>2005-09-08 15:45:02</datecreated>
  <lastmodified>2005-12-20 20:58:41</lastmodified>
  <attributes>
    <attribute id="6"><![CDATA[ Nur bei Opencaching]]></attribute>
  </attributes>
</cache>

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ä)

<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"><![CDATA[Gefunden]]></type>
  <date>2005-05-18</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>
</cachelog>

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>
  <attributes spoiler="0" display="1" />< /SPAN>
  <datecreated>2005-12-24 01:01:38</datecreated>
  <lastmodified>2005-12-24 01:01:38</lastmodified>
</picture>

removedobject (gelöte 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 üine Gebietsauswahl.

Zu üagende Daten auswäen

Folgende Parameter stehen zur Verfüum die zu üagenden Daten auszuwäen.

Die Werte dü1 oder 0 sein, Default ist 0.
0=Datensäe nicht üagen
1=Datensäe üagen

• user
• cache
• cachedesc
• cachelog
• picture
• removedobject

modifiedsince

Alle Datensä üagen, 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öch.

Nach Land

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

Füder muss dabei angegeben werden, ob nur Bilder üagen 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ä üagen, die mit Caches in Zusammenhang stehen, die in diesem Gebiet versteckt wurden. User-Records werden nicht üagen, removedobjects werden alle ügen.

Nach cacheid

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

Füder muss dabei angegeben werden, ob nur Bilder üagen 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/ocxml11.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/ocxml11.php?modifiedsince=<date>&cache=1&cachedesc=1&cachelog=1&picture=1&removedobject=1&country=DE&picturefromcachelog=1

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

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

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

6. Alle Bilder von Caches abrufen die in Deutschland versteckt sind
http://www.opencaching.de/xml/ocxml11.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/ocxml11.php?modifiedsince=<date>&picture=1&country=DE&picturefromcachelog=1

Diese Anfragen werden mit einem kurzen XML-Stream beantwortet, der die XML-Session-Id zurüt. Mit dieser Id kön 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 Sessionid ist 24h gü danach muss eine neue sessionid angefordert werden. Die Anzahl der Datensä muss nicht exakt mit den üagenen ünstimmen - mehr Datensäe werden jedoch auf keinen Fall üagen. Die Summe der Datensäe ist in diesem Beispiel 1205 - es werden also 3 Aufrufe benöt (500, 500, 205 Datensäe).

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

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/ocxml11.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öche Werte sind 0, zip, bzip2, gzip. Null bedeutet hier keine Kompression. Wird keine Kompression angegeben, wird zip verwendet.

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

XML-Optionen

Die folgenden XML-Optionen mübei jedem Aufruf üben 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/ocxml11.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/ocxml11.php?sessionid=4711&file=1&charset=utf-8&cdata=1&xmldecl=0&ocxmltag=0&doctype=0

Sonstige Bemerkungen

• Fü ersten Aufruf des Interface muss als modifiedsince das Datum 1.8.2005 um 00:00:00 Uhr angegeben werden. Es gibt keine Datensäe die vor diesem Datum angelegt wurden.
• Um Probleme wegen Differenzen der Uhrzeit zwischen Client und Server zu umgehen, muss fü nästen 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.1" date="2006-03-10 18:37:34" since="2006-03-08 22:02:42">
• Zeitverschiebungen / unterschiedliche Zeitzonen zwischen Client und Server werden nicht unterstü
• Das XML-Dokument enthä folgende DTD (Document Type Definition): http://www.opencaching.de/xml/ocxml11.dtd
• Äderungen werden des XML-Interface werden im Entwicklerforum bekanntgegeben: http://develforum.opencaching.de/viewforum.php?f=2
• Fragen zum Interface kön ebenfalls im Entwicklerforum gestellt werden: http://develforum.opencaching.de/viewforum.php?f=2
• Der Quellcode des Interface kann hier downgeloadet werden: http://devel.opencaching.de/viewcvs/viewcvs.cgi/html/xml/ocxml11.php?rev=1.2&content-type=text/vnd.viewcvs-markup
• Eine Referenzimplementierung kann hier downgeloadet werden: http://devel.opencaching.de/viewcvs/viewcvs.cgi/html/util/ocxml11client/

Lizenz:

• der Quellcode steht unter der GNU Gerneral Public Licenses
• Fuer die Nutzung des XML-Interface ist eine gesonderte Nutzungserlaubnis durch den Betreiber von opencaching.de notwendig. Darin wird geregelt, auf welche Art und Weise die bezogenen Daten genutzt werden duerfen.