# Dokumentation Opencaching XML-Interface Version 1.1

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

## 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 eine Cachebeschreibung geändert wird, ändert 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ü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"><![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= "" 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ä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"><![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ö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

- 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ätz ü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/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ü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 Sessionid ist 24h gültig, danach muss eine neue sessionid angefordert werden. 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/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ö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/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ü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/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ü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.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ützt.
- Das XML-Dokument enthält folgende DTD (Document Type Definition): http://www.opencaching.de/xml/ocxml11.dtd
- Änderungen werden des XML-Interface werden im Entwicklerforum bekanntgegeben: http://develforum.opencaching.de/viewforum.php?f=2
- Fragen zum Interface können 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
- für Daten die über das XML-Interface downgeloadet werden, gelten die Nutzungsbedingungen von Opencaching.de http://www.opencaching.de/articles.php?page=impressum#tos