API für Entwickler
Wir bieten einen Großteil der Eventdaten über unsere API an, so dass du die Schnittstelle sowohl zum Auslesen als auch zum Schreiben nutzen kannst.
Generelles
Es handelt sich um eine REST-API, mit der du per HTTP kommunizieren kannst. Die Authentifizierung erfolgt über HTTP Basic Authentication, wofür du Benutzername und Passwort deines Benutzerprofils benutzen kannst.
Lesezugriff
Wir bieten die Formate XML, Atom und iCalendar an. Die Datensätze sind partitioniert, es wird also immer nur ein
Teil der Gesamtergebnisse zurückgegeben. Mit dem Parameter page kann man durch die einzelnen Seiten
navigieren (bspw. ?page=2).
Die Ausgabe kann über weitere Parameter gefiltert und somit näher eingeschränkt werden. Die verfügbaren Parameter (alle optional) sind:
what(Suchbegriff)where(Städtename)when(Zeitraum oder Datum, Standard: zukünftig)distance(Umkreis in km, Standard: 25 km)category(ID einer Kategorie, weitere Infos dazu)filter(zusätzliche Filterung)
Wird when übergeben, so muss es ein Wert der folgenden Liste sein:
upcoming(zukünftige Events, Standard)today(heutige Events)next7days(Events in den nächsten 7 Tagen)weekend(Events am kommenden/aktuellen Wochenende)past(vergangene Events)YYYY(Jahr)YYYY-MM(Jahr und Monat)YYYY-MM-DD(Jahr, Monat und Tag)
Wird filter übergeben, so muss es ein Wert der folgenden Liste sein:
fresh(Sortierung nach Zeitpunkt der Eintragung auf venteria)popular(Sortierung nach Teilnehmerzahl)
Beispiele
| Daten | Formate | ||
|---|---|---|---|
| Alle heutigen Events | XML | Atom | iCal |
| Die 30 neuesten Events | XML | Atom | iCal |
| Die 30 populärsten Events | XML | Atom | iCal |
| Alle Events einer Stadt | XML | Atom | iCal |
| Alle Events einer Location | XML | Atom | iCal |
| Alle Events einer Gruppe | XML | Atom | iCal |
| Alle Events eines Users | XML | Atom | iCal |
| Alle Events zu einem Tag | XML | Atom | iCal |
| Alle Events zu einem Suchbegriff | XML | Atom | iCal |
| Alle vergangenen Events zu einem Suchbegriff | XML | Atom | iCal |
| Alle Events zu einem Suchbegriff in einer Stadt | XML | Atom | iCal |
| Alle vergangenen Events zu einem Suchbegriff in einer Stadt | XML | Atom | iCal |
Kategorien
Die Kategorien müssen über ihre jeweilige ID referenziert werden, hier die Aufschlüsselung der Kategorie-IDs:
| Kategorie | ID |
|---|---|
| Musik | 2 |
| - Rock & Pop | 17 |
| - Hard & Heavy | 18 |
| - Hip Hop, Rap, Black | 19 |
| - House, Electro | 28 |
| - Jazz, Blues, Swing | 20 |
| - Liedermacher, Folk | 29 |
| - Schlager, Volksmusik | 21 |
| Kultur | 4 |
| - Klassikkonzert | 11 |
| - Musical | 12 |
| - Oper | 13 |
| - Theater | 14 |
| - Lesung | 15 |
| - Kabarett | 16 |
| Sport | 7 |
| - Fußball | 22 |
| - Motorsport | 23 |
| - Tennis | 24 |
| - Eissport | 25 |
| - Handball | 26 |
| - Basketball | 27 |
| Party | 6 |
| - Disco | 30 |
| - Geburtstag | 31 |
| Großveranstaltung | 5 |
| Treffen | 3 |
| Lehrveranstaltungen | 9 |
| Sonstiges | 1 |
Schreibzugriff
Um einen Event anzulegen, müssen die erforderlichen Parameter als HTTP-POST an folgende URL gesendet werden: http://venteria.com/events
Event-Attribute
| Parameter | Beschreibung | Anforderung |
|---|---|---|
| summary | Titel des Events | erforderlich |
| location | Veranstaltungsort | erforderlich |
| datetime_start | Beginn | erforderlich |
| datetime_end | Ende | optional |
| fulltime | ganztags | optional (Standard: false) |
| status | public oder private |
optional (Standard: public) |
| description | Beschreibung | optional |
| url | Website | optional |
| description | Beschreibung | optional |
| category_id | ID der Kategorie | optional |
| tag_list | Liste von Tags | optional |
Zum Beispiel könnte ein Request wie folgt aussehen (hier über cURL):
curl -X POST http://localhost:3000/events.xml
--basic -u DEIN_BENUTZERNAME[:DEIN_PASSWORT]
-d '
event[summary]=Titel+des+Events&
event[location]=Weserstadion,+Bremen&
event[datetime_start]=2008-05-26T09:00:00+01:00&
event[datetime_end]=2008-05-26T09:00:00+01:00&
event[fulltime]=false&
event[description]=Es+geht!&
event[url]=http://venteria.com/api'
