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 (Stadt, Adresse oder Geokoordinaten -> Latitude,Longitude)
  • when (Zeitraum oder Datum, Standard: zukünftig)
  • distance (Umkreis in km, Standard: 25 km)
  • 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 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

Schreibzugriff

Um einen Event anzulegen, müssen die erforderlichen Parameter als HTTP-POST an folgende URL gesendet werden: http://venteria.com/events.xml

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
tag_list Liste von Tags optional
url Website optional
poster_url URL des Bildes optional
locked Bearbeitung sperren optional (Standard: false)

Zum Beispiel könnte ein Request wie folgt aussehen (hier über cURL):

curl -X POST http://venteria.com/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'

Teilnahmen

Über die API kann auch der Teilnahmestatus bearbeitet werden. So kann man sich für ein Event eintragen bzw. die Teilnahme wieder löschen.

Teilnahme-Attribute

Parameter Beschreibung Anforderung
status attending oder watching erforderlich

Beispiel zum Erstellen einer Teilnahme:

curl -X POST http://venteria.com/events/EVENT-ID/participations.xml
--basic -u DEIN-BENUTZERNAME
-d 'status=attending'

Beispiel zum Bearbeiten einer Teilnahme:

curl -X PUT http://venteria.com/events/EVENT-ID/participations/PARTICIPATION-ID.xml
--basic -u DEIN-BENUTZERNAME
-d 'status=watching'

Beispiel zum Löschen einer Teilnahme:

curl -X DELETE http://venteria.com/events/EVENT-ID/participations/PARTICIPATION-ID.xml
--basic -u DEIN-BENUTZERNAME