Documentation Opencaching XML Interface Version 1.2

The XML interface allows for automated check of all the caches, log entries, users and / or images. This interface is not intended for end users, but primarily for Web site developers.
Output Format

The output is one or more xml, zip, gz or bz2 files. There are 2 transfer modes available: in packages of 500 records, or in a file.

The following XML parts are available. You will always be displayed in this order:

   1. user (user)
   2. caches (caches)
   3. cachedesc (cache descriptions)
   4. cachelog (log entries)
   5. picture (pictures)
   6. removedobject (deleted items)

General XML elements

lastmodified
Date on which this record was last changed. It does not take into account dependencies. I.e. If a cache description will be changed, only their lastmodified, but not the cache. Dates are always in the form "yyyy-mm-dd hh: mm: ss or yyyy-mm-dd"

DateCreated
Date on which this record was created.

id
Distinctions must be the identifier id () and the uuid (universally unique identifier). The id (number) is valid only on each web page identifier, while the alphanumeric uuid (sequence) on each side of the open caching data used should be valid. For example, when the data synchronization of www.opencaching.de and devel.opencaching.de devel.opencaching.de is produced on a new id for the record and the beibhalten uuid.

Attribute List

<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 [Night Cache]]>
  </ 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 [Only 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 [only link]]>
  </ 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 (stamp required)]]>
  </ attr>
</ attrList>

user (user)

<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

Username
pmr

1: The user has specified a PMR radio on channel 2 to take on tour.
0: No Information
cache (caches)

<cache>
  <id id="270"> D455C916-7737-8210-F7FF-C6872E561CEB </ id>
  <user id="113" uuid= <"CAA9E3C5-50DF-4E9E-191F-CECABA6A8A19"> [CDATA [Team Scavenger hunt ]]></ user>
  <name> <! [CDATA [Pegeluhr ]]></ name>
  <longitude> 8.45058 </ longitude>
  <latitude> 49.46393 </ latitude>
  <type id="2" short="Trad."> <[CDATA []]></ normal cache type>
  <status id="2"> <! [CDATA [Currently not available ]]></ status>
  <country id="DE"> <! [CDATA [Germany ]]></ country>
  <size id="2"> <! [CDATA []]></ micro-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 [Only Opencaching ]]></ attribute>
  </ attributes>
</ cache>
cachedesc (cache descriptions)

<cachedesc>
  <id id="5697"> 9BA489ED-AC62-6EC8-B26D-4D52DF3CD008 & </ id>
  <cacheid id="4927"> AB551E31-8633-0CD1-26AD-324355D4E920 </ CacheID>
  <language id="EN"> <! [CDATA []]></ English language>
  <shortdesc> <! [CDATA [drive-in cache especially for motorcyclists ]]></ shortdesc>
  <desc <html="1"> [CDATA [This MoCache is intended to connect the series to other MoCache
motorcycle-friendly caches on The Alb. Furthermore this great road
and between Erpfingen 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 (log entries)

<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 Scavenger Hunt ]]></ user>
  <logtype id="1" recommended="0"> <! [CDATA [Found ]]></ type>
  <date> 2005-05-18 </ date>
  <text> <found! Good [CDATA [. <br />
Greetings from <br />
Volker ]]></ text>
  <DateCreated> 2005-12-24 06:24:07 </ DateCreated>
  <lastmodified> 2005-12-24 06:24:07 </ lastmodified>
</ cachelog>
picture (pictures)

<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 []]></ figures shuffling title>
  <desc html="0"> </ desc>
  <object id="73240" type="1" typename= "cachelog"> 4FE4B999-315D-43C1-11C2-2B81E68168CD </ object>
  <attribute spoiler="0" display="1" /> </ SPAN>
  <DateCreated> 2005-12-24 01:01:38 </ DateCreated>
  <lastmodified> 2005-12-24 01:01:38 </ lastmodified>
</ picture>
removedobject (deleted items)

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

The selection is made on the one modifiedsince by the parameters that are controlled with the incremental updates, the other on a site selection.
Selecting Data to be transmitted

The following parameters are available by selecting the data to be transferred.

The values may be 1 or 0, default is 0
0 = not transfer records
1 = data transfer

    * User
    * Cache
    * Cachedesc
    * Cachelog
    * Picture
    * Removedobject

modifiedsince
All records transferred, which were created or modified after that date. The date format is yyyymmddhhmmss

Site selection
It must be made no territorial selection. A combination of land, coordinates or CacheID is not possible.

By Country
Parameters country ... this parameter is specified, only records transferred that are associated with caches that were hidden in this country. User records are not transferred, all will removedobjects Übetragung.

For images this must be specified whether only images can be transmitted from the cache, or originate from Cachelogs:
Parameters: picturefromcachelog = 0 / 1, default 0

By coordinates
Parameters lat, lon, distance ... these parameters are specified, only records transferred that are associated with caches that were hidden in this area. User records are not transferred, all will removedobjects Übetragung.

After CacheID

Parameters CacheID ... this parameter is specified, only records transferred that are associated with cache. User records are not transferred, all will removedobjects Übetragung.

For images this must be specified whether only images can be transmitted from the cache, or originate from Cachelogs:
Parameters: picturefromcachelog = 0 / 1, default 0

After Waypoint
Parameter wp ... as CacheID, except that instead of the CacheID Opencaching waypoint is used.

After uuid
Parameter uuid ... as CacheID, except that instead of CacheID the UUID of the cache is used.

Examples

1. All data incrementally retrieve
http://www.opencaching.us/xml/ocxml11.php?modifiedsince=<date>&user=1&cache=1&cachedesc=1&cachelog=1&picture=1&removedobject=1

2. All data from U.S. incrementally retrieve
http://www.opencaching.us/xml/ocxml11.php?modifiedsince=<date>&cache=1&cachedesc=1&cachelog=1&picture=1&removedobject=1&country=US&picturefromcachelog=1

3. All caches without incrementally retrieve logs from Germany
http://www.opencaching.us/xml/ocxml11.php?modifiedsince=<date>&cache=1&cachedesc=1&picture=1&removedobject=1&country=DE

4. All data within a radius of 100 km to retrieve
http://www.opencaching.us/xml/ocxml11.php?modifiedsince=<date>&cache=1&cachedesc=1&cachelog=1&picture=1&removedobject=1&lat=48&lon=9&distance=100&picturefromcachelog=1

5. Retrieve all images
http://www.opencaching.us/xml/ocxml11.php?modifiedsince=<date>&picture=1

6. All pictures of caches that are hidden in U.S. to retrieve
http://www.opencaching.us/xml/ocxml11.php?modifiedsince=<date>&picture=1&country=US

7. All pictures from their caches and retrieve the logs are hiding in U.S.
http://www.opencaching.us/xml/ocxml11.php?modifiedsince=<date>&picture=1&country=US&picturefromcachelog=1

These questions will be answered with a short XML stream that returns the XML Session-Id. With this id, the data can then be retrieved.

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

The SessionID is valid for 24 hours, then must be a new sessionid be requested. The number of records does not exactly match the transferred - but more records are transferred under any circumstances. The sum of the records in this example is 1205 - it will therefore requires 3 calls (500, 500, 205 records).

The data can then be retrieved with the following request:
http://www.opencaching.us/xml/ocxml11.php?sessionid=12345&file=1
http://www.opencaching.us/xml/ocxml11.php?sessionid=12345&file=2
http://www.opencaching.us/xml/ocxml11.php?sessionid=12345&file=3

All query results by calling

To retrieve all results to a file must be at the call of the session parameters are set to 0.

EXAMPLES:
http://www.opencaching.us/xml/ocxml11.php?modifiedsince=<date>&user=1&cache=1&cachedesc=1&cachelog=1&picture=1&removedobject=1&session=0

Setting File Compression

File compression can be adjusted with the parameters weren zip. Possible values are 0, zip, bzip2, gzip. Zero here means no compression. Where there is no compression, zip is used.

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

XML options

The following XML options must be passed on each call.

xmldecl ... 0 = no xml declaration / (default) 1 = xml-declaration
doctype ... 0 = No Xml-Document-Type Definition / (default) 1 = Xml-Document-Type Definition
ocxmltag ... 0 = no oc11xml tag at the beginning / (default) 1 = oc11xml tag at the beginning
cdata ... 0 = control characters in XML text mask (eg & => &) / (default) 1 = text inclose in CDATA sections
charset ... (Default) iso-8859-1 / utf-8
attrList ... (Default) 0 = no attribute list to transfer / transmit 1 = attribute list
Examples

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

Other observations

    * To be the first call to the interface must be specified as modifiedsince date 1.8.2005 at 00:00:00 Clock. There are no records that were created before that date.
    * To avoid problems due to the time differences between client and server, you must specify for the next Incremental retrieval of data, the date at the top of the XML file, minus 1 seconds:

      <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">
    * Time-shifting / time zone differences between client and server are not supported.
    * The XML document contains the following DTD (Document Type Definition): http://www.opencaching.us/xml/ocxml11.dtd
    * Changes to the XML interface will be announced in the developer forum: http://develforum.opencaching.de/viewforum.php?f=2
    * Questions about the interface can also be placed in the developer forum: http://develforum.opencaching.de/viewforum.php?f=2
    * The source code of the interface can be downloaded here: http://devel.opencaching.de/viewcvs/viewcvs.cgi/html/xml/ocxml11.php?rev=1.2&content-type=text/vnd.viewcvs-markup
    * A reference implementation can be downloaded here: http://devel.opencaching.de/viewcvs/viewcvs.cgi/html/util/ocxml11client/

License:

    * The source code is available under GNU Gerneral Public Licenses
    * For data to be downloaded via the XML interface, subject to the Terms of Opencaching.de http://www.opencaching.de/articles.php?page=impressum # tos