Wichtig!
Um die Schnittstelle nutzen zu können, muss man einen eigenen culturebase Account besitzen. Dieser muss dann für die Schnittstelle freigeschaltet sein.
Die Authentifizierung erfolgt über die POST Parameter "u" (Accountname) und "pwd" (Passwort)
Weitere Informationen zur Erstellung eines Accounts erhalten Sie bei der
Redaktion.
Unter der Adresse
http://cb.heimat.de/interface/events.php
existiert eine Schnittstelle, die es ermöglicht, parametrisierbare Abfragen der Termindatenbank durchzuführen.
Sowohl die Anfrage an die Schnittstelle, als auch die zurückgegebenen Daten sind im XML Format realisiert.
Das XML Format für die Anfrage kann unter
http://cb.heimat.de/interface/schema/filterformat.xsd
eingesehen werden. Die Anfrage muss per POST Request gestellt werden. Grund dafür ist, daß ausschließlich über Daten im XML
Format kommuniziert wird. Das ausgelieferte XML hat dasselbe Format, welches auch für einen Import benutzt wird. Es liegt unter
http://cb.heimat.de/interface/schema/interfaceformat.xsd.
Um eine Abfrage per POST Request zu realisieren, existieren etliche Möglichkeiten. Unter anderem ist es möglich, mit der freien Bibliothek Snoopy (
http://snoopy.sourceforge.net/) oder
mit der PHP Implementierung der libcurl Bibliothek cURL (
http://de2.php.net/manual/de/ref.curl.php) POST Requests abzusetzen.
Ein Beispielskript realisiert mit Snoopy, sähe z.B. so aus:
require_once ('lib/Snoopy.class.php');
header("Content-Type: text/xml");
// neues Snoopy Objekt erstellen
$snoopy = new Snoopy();
// URL setzen
$url = "http://cb.heimat.de/interface/events.php";
// Benutzername und Passwort setzen
$postVars['u'] = <ACCOUNTNAME>;
$postVars['pwd'] = <PASSWORT>;
// Filterstring setzen
$postVars['filter'] = '<filterlist>...FILTERLIST XML STRING...<filterlist>';
if($snoopy->submit($url, $postVars))
{
echo $snoopy->results;
} else
{
echo "<error>error fetching document: ".$snoopy->error."</error>";
}
Nachfolgend gültige
Beispiele für XML Filter Strings:
Beispiel 1:
Alle Termine vom 27.1.2008 bis zum 3.2.2008 aus Aachen.
<filterlist>
<filter useTimestamp="0" offset="0" count="0" short="false">
<date type="start">2008-01-27</date>
<date type="end">2008-02-03</date>
<city isId="1">2384</city>
</filter>
</filterlist>
Beispiel 2:
Alle Termine vom 27.1.2008 bis zum 3.2.2008 vom Veranstaltungsort mit der ID 3493 (Raststätte).
<filterlist>
<filter useTimestamp="0" offset="0" count="0" short="false">
<date type="start">2008-01-27</date>
<date type="end">2008-02-03</date>
<location isId="1">3493</city>
</filter>
</filterlist>
Beispiel 3:
Alle Termine vom 27.1.2008 bis zum 15.2.2008 vom Veranstaltungsort mit der ID 3493 (Raststätte). Allerdings nur 3 Termine (count=3) in Kurzform (short="true") und beginnend ab dem 2. Termin (offset=2)
<filterlist>
<filter useTimestamp="0" offset="2" count="3" short="true">
<date type="start">2008-01-27</date>
<date type="end">2008-02-15</date>
<location isId="1">3493</location>
</filter>
</filterlist>
Es existieren folgende Parameter, um die Abfrage der Termine zu steuern:
- id: die ID eines Termins
- date: Start- oder Enddatum
- title: Suche nach einem bestimmten Titel
- category: Angabe einer Culturebase Kategorie. Die IDs der Kategorien finden sich unter dieser Adresse: http://cb.heimat.de/interface/api/categories.php?catSystemId=6
- city: die Culturebase ID der Stadt. Eine vollständige Liste kann hier heruntergeladen werden: http://cb-in.de/data/city_ids.zip
- location: Die Culturebase ID des Veranstaltungsortes. Eine vollständige Liste kann hier heruntergeladen werden: http://cb-in.de/data/location_ids.zip
- region: Die Culturebase ID der Region. Eine vollständige Liste kann hier heruntergeladen werden: http://cb-in.de/data/region_ids.zip
- keyword: Suche über das Schlüsselwortfeld der Termine
- offset: Startindex der Ergebnismenge der Abfrage.
- count: Anzahl der Termine, die zurückgegeben werden sollen.
- type: Typ der gesuchten Termine. 1 für Produktionen, 2 für einzelne Termine und 0 für unbekannt, bzw. beide Typen.
- short: wenn short = true dann nur eine kurze Übersicht liefern
