Die Eventkrake 2 API

Die Eventkrake 2 API ermöglicht es, Daten aus der Eventkrake zu lesen und Daten in die Eventkrake zu schreiben. Für einige API-Aufrufe werden eine gültige E-Mail-Adresse samt Schlüssel benötigt. Diese kannst Du hier erfragen.

Der Grundsätzliche Aufbau von Events und Locations

Die API gibt grundsätzlich JSON-kodierte Daten zurück.

Event

  • useremail Die E-Mail des Users, der dieses Event erstellt hat.
  • id Die Id des Events.
  • locationid Die Id der Location an der dieses Event stattfindet.
  • datetime Der Anfang des Events als ISO-8601-Datum und -Zeit (yyyy-mm-ddThh:mm:ss).
  • datetime_end Das Ende des Events als ISO-8601-Datum und -Zeit (yyyy-mm-ddThh:mm:ss).
  • title Der Titel des Events.
  • excerpt Eine kurze Zusammenfassung des Events.
  • text Die ausführliche Beschreibung des Events.
  • url Eine Webseite mit weiteren Infos zum Event.
  • image Die URL zu einem Bild für das Event.
  • visible true, wenn das Event öffentlich angezeigt werden soll, false sonst.
  • categories Die Kategorien des Events als Array von IDs. Siehe getcategories für die Klarnamen.
  • festival Ggf. die ID eines Festivals, zu dem dieses Event gehört. Siehe getfestivals für weitere Informationen.
  • tags Ein beliebig nutzbares Zeichenkettenfeld.

Location

  • useremail Die E-Mail des Users, der diese Location erstellt hat.
  • id Die Id der Location.
  • name Der Name der Location.
  • address Die Adresse der Location. Diese muss keiner genauen Postadresse entsprechen, sollte aber den Nutzer nicht verwirren.
  • lat Der Breitengrad der Location als float.
  • lng Der Längengrad der Location als float.
  • text Die ausführliche Beschreibung der Location.
  • url Eine Webseite mit weiteren Infos zur Location.
  • image Die URL zu einem Bild für die Location.
  • visible true, wenn die Location öffentlich angezeigt werden soll, false sonst.
  • categories Die Kategorien der Location als Array von IDs. Siehe getcategories für weitere Informationen.
  • festivals Ggf. Festivals, die an dieser Location stattfinden als Array von alphanumerischen IDs. Siehe getfestivals für weitere Informationen.
  • tags Ein beliebig nutzbares Zeichenkettenfeld.

Der Zugriff auf die API

Über die URL http://api.eventkrake.de/{aufruf}/ wird ein HTTP POST mit entsprechenden Parametern geschickt. Der Server antwortet mit einem Statuscode und ggf. Daten. Folgende Statuscodes sind möglich (nicht abschließend, siehe dazu bei den einzelnen Aufrufen):

  • 200 OK
  • 400 Bad Request Die Anfrage wurde nicht verstanden.
  • 401 Unauthorized Authentifizierung mit E-Mail-Adresse und Schlüssel fehlgeschlagen.
  • 404 Not Found Bei einer Aktualisierung wurde das entsprechende Objekt nicht gefunden.
  • 500 Internal Server Error Ein interner Fehler. Eine Meldung an uns wäre nett.

Folgende Werte kann {aufruf} annehmen:

API ohne Authentifizierung

getevents

Gibt mehrere Events mit den zugehörigen Locations zurück. Werden keine Parameter gesetzt werden alle Events bis zu limit zurückgegeben. Die Parameter werden UND-verknüpft.

Parameter:

  • event_useremail string (optional) Gibt nur Events zurück, die zu dieser E-Mail-Adresse gehören.
  • event_ids string (optional) Eine komma-separierte Liste von Event-Ids, die zurückgegeben werden sollen.
  • event_locationids string (optional) Eine komma-separierte Liste von Location-Ids. Es werden nur Events zurückgegeben, die an diesen Locations stattfinden.
  • event_datestart string (optional) Ein DateTime-String, wie von PHP unterstützt. Wenn keiner angegeben ist, wird der aktuelle Zeitpunkt mit genullten Minuten angenommen („YmdHi00“). Wenn sowohl event_datestart und event_dateend nicht angegeben sind, werden Veranstaltungen ausgegeben, die gerade laufen.
  • event_dateend string (optional) Ein DateTime-String, wie von PHP unterstützt. Wenn keiner angegeben ist, wird der aktuelle Zeitpunkt mit genullten Minuten angenommen („YmdHi00“). Wenn sowohl event_datestart und event_dateend nicht angegeben sind, werden Veranstaltungen ausgegeben, die gerade laufen.
  • event_search string (optional) Ein Suchstring, der Eventtitel, Eventauszug, Eventtext und Eventtags durchsucht. Die Zeichen , . + – Zeilenumbruch und Tabulator werden dabei entfernt und eine MySQL-MATCH im BOOLEAN MODE durchgeführt.
  • event_tags string (optional) Ein Suchstring, der nur die Eventtags durchsucht. Die Zeichen , . + – Zeilenumbruch und Tabulator werden dabei entfernt und eine MySQL-MATCH im BOOLEAN MODE durchgeführt.
  • event_categories array (optional) Ein Array der IDs von Kategorien. Die Events müssen mindestens einer Kategorie angehören.
  • event_festivals array (optional) Ein Array der IDs von Festivals. Die Events müssen mindestens einem Festival angehören.
  • location_search string (optional) Ein Suchstring, der Locationname, Locationadresse, Locationtext und Locationtags durchsucht. Die Zeichen , . + – Zeilenumbruch und Tabulator werden dabei entfernt und eine MySQL-MATCH im BOOLEAN MODE durchgeführt.
  • location_tags string (optional) Ein Suchstring, der nur die Locationtags durchsucht. Die Zeichen , . + – Zeilenumbruch und Tabulator werden dabei entfernt und eine MySQL-MATCH im BOOLEAN MODE durchgeführt.
  • location_categories array (optional) Ein Array der IDs von Kategorien. Die Locations müssen mindestens einer Kategorie angehören.
  • location_festivals array (optional) Ein Array der IDs von Festivals. Die Locations müssen mindestens einem Festival angehören.
  • location_bounds [lat1,lng1],[lat2,lng2] (optional) Verbindet zwei Geokoordinaten zu einem Rechteck und gibt nur die Locations im Rechteck zurück. Die Geokoordinaten sollten als float angegeben sien.
  • limit int (optional) Die maximale Anzahl an Events, die zurückgegeben werden soll. Der Standardwert ist 1.000.
  • Sichtbarkeit der Events Wenn eine gültige E-Mail-Adresse und Schlüssel angegeben sind, werden auch Events, die nicht sichtbar (visible ist false) sind, zurückgegeben.
    • email string (optional) Eine E-Mail-Adresse.
    • key string (optional) Ein Schlüssel.

Returns: Ein Objekt mit einem Events-Objekt, das Event-Objekte nach Startdatum sortiert enthält und einem Locations-Objekt, das Location-Objekte enthält. Die Schlüssel des Events-Objekt sind datetime_eventid, die Schlüssel des Locations-Objekts sind die Location-IDs.

getlocations

Gibt mehrere Locations zurück. Werden keine Parameter gesetzt werden alle Location bis zu limit zurückgegeben.

Parameter:

  • OP AND|OR (optional) Legt fest, ob die Parameter UND- oder ODER-verknüpft werden. Der Standardwert ist AND.
  • location_useremail string (optional) Gibt nur Locations zurück, die zu dieser E-Mail-Adresse gehören.
  • location_ids string (optional) Eine komma-separierte Liste von Location-Ids, die zurückgegeben werden sollen.
  • location_search string (optional) Ein Suchstring, der Locationname, Locationadresse, Locationtext und Locationtags durchsucht. Die Zeichen , . + – Zeilenumbruch und Tabulator werden dabei entfernt und eine MySQL-MATCH im BOOLEAN MODE durchgeführt.
  • location_tags string (optional) Ein Suchstring, der nur die Locationtags durchsucht. Die Zeichen , . + – Zeilenumbruch und Tabulator werden dabei entfernt und eine MySQL-MATCH im BOOLEAN MODE durchgeführt.
  • location_categories array (optional) Ein Array der IDs von Kategorien. Die Locations müssen mindestens einer Kategorie angehören.
  • location_festivals array (optional) Ein Array der IDs von Festivals. Die Locations müssen mindestens einem Festival angehören.
  • location_bounds [lat1,lng1],[lat2,lng2] (optional) Verbindet zwei Geokoordinaten zu einem Rechteck und gibt nur die Locations im Rechteck zurück. Die Geokoordinaten sollten als float angegeben sien.
  • visible bool (optional) Wenn visible false ist, werden nur nicht sichtbare Locations zurückgegeben, sonst nur sichtbare. Der Standardwert sind sichtbare Locations.
  • limit int (optional) Die maximale Anzahl an Locations, die zurückgegeben werden soll. Der Standardwert ist 1.000.

Returns: Ein Locations-Objekt, das Location-Objekte enthält. Die Schlüssel des Locations-Objekts sind die Location-IDs.

getevent

Gibt ein JSON-kodiertes Event zurück.

  • event_id int Die ID des Events.

Returns: Das Event im JSON-Format oder einen Statuscode 404, wenn das Event nicht gefunden wurde.

getlocation

Gibt eine JSON-kodierte Location zurück.

  • location_id int Die ID der Location.

Returns: Die Location im JSON-Format oder einen Statuscode 404, wenn die Location nicht gefunden wurde.

getcategories

Gibt die Kategorien mit ID und Namen zurück.

Returns: Ein Objekt aus Kategorien mit den Eigenschaften id und category und der ID als Objekt-Schlüssel.

API mit Authentifizierung

Bei den folgenden Aufrufen müssen immer folgender Felder mitgegeben werden:

  • email string Eine gültige E-Mail-Adresse.
  • key string Der dazugehörige Schlüssel.

Werden diese Felder weggelassen, antwortet die API mit einem Statuscode 401.

getfestivals

Returns: Ein Objekt aus Festivals mit der Festival-ID als Schlüssel und folgenden Festival-Attributen: id, long_title, date_start und date_end.

verifyuserkey

Returns: true, wenn E-Mail-Adresse und Schlüssel korrekt sind.

insertevent

Fügt ein neues Event hinzu.

Parameter:

  • title string Der Titel des Events.
  • locationid int (optional) Die Location-ID, an der das Event stattfindet.
  • datetime string (optional) Ein DateTime-String, wie von PHP unterstützt. Wenn keiner angegeben ist, wird der aktuelle Zeitpunkt angenommen.
  • datetime_end string (optional) Ein DateTime-String, wie von PHP unterstützt. Wenn keiner angegeben ist, wird der aktuelle Zeitpunkt plus 2 Stunden angenommen.
  • excerpt string (optional) Eine kurze Zusammenfassung des Events.
  • text string (optional) Eine ausführliche Beschreibung des Events.
  • url string (optional) Eine Webseite mit weiteren Informationen zum Event.
  • image string (optional) Eine URL zu einem Bild.
  • categories array (optional) Ein Array aus Kategorie-IDs zu denen das Event gehört.
  • festival string (optional) Die ID eines Festivals zu denen das Event gehört.
  • tags string (optional) Ein beliebig nutzbares Zeichenkettenfeld.
  • visible bool (optional) Wenn visible false ist, wird das Event nicht öffentlich angezeigt. Der Standardwert ist true.

Returns: Das eingefügte Event im Erfolgsfall, sonst einen Statuscode 400.

alterevent

Ändert ein bestehendes Event. Eigenschaften, die ausgelassen werden, bleiben unverändert.

Parameter:

  • id int Die ID des zu ändernden Events.
  • title string (optional) Der Titel des Events.
  • locationid int (optional) Die Location-ID, an der das Event stattfindet.
  • datetime string (optional) Ein DateTime-String, wie von PHP unterstützt. Wenn keiner angegeben ist, wird der aktuelle Zeitpunkt angenommen.
  • datetime_end string (optional) Ein DateTime-String, wie von PHP unterstützt. Wenn keiner angegeben ist, wird der aktuelle Zeitpunkt plus 2 Stunden angenommen.
  • excerpt string (optional) Eine kurze Zusammenfassung des Events.
  • text string (optional) Eine ausführliche Beschreibung des Events.
  • url string (optional) Eine Webseite mit weiteren Informationen zum Event.
  • image string (optional) Eine URL zu einem Bild.
  • categories array (optional) Ein Array aus Kategorie-IDs zu denen das Event gehört.
  • festival string (optional) Die ID eines Festivals zu denen das Event gehört.
  • tags string (optional) Ein beliebig nutzbares Zeichenkettenfeld.
  • visible bool (optional) Wenn visible false ist, wird das Event nicht öffentlich angezeigt. Der Standardwert ist true.

Returns: Das geänderte Event im Erfolgsfall, sonst einen Statuscode 404.

insertlocation

Fügt eine neue Location hinzu.

Parameter:

  • name string Der Name der Location.
  • address string Die Adresse der Location. Diese sollte aussagekräftig und menschlich auffindbar sein.
  • lat float Der Breitengrad der Location.
  • lng float Der Längengrad der Location.
  • text string (optional) Eine Beschreibung der Location.
  • url string (optional) Eine Webseite mit weiteren Informationen zur Location.
  • image string (optional) Eine URL zu einem Bild.
  • categories array (optional) Ein Array aus Kategorie-IDs zu denen die Location gehört.
  • festivals string (optional) Ein Array aus Festival-IDs zu denen die Location gehört.
  • tags string (optional) Ein beliebig nutzbares Zeichenkettenfeld.
  • visible bool (optional) Wenn visible false ist, wird die Location nicht öffentlich angezeigt. Der Standardwert ist true.

Returns: Die eingefügte Location im Erfolgsfall, sonst einen Statuscode 400.

alterlocation

Ändert eine bestehende Location. Eigenschaften, die ausgelassen werden, bleiben unverändert.

Parameter:

  • id int Die ID der zu ändernden Location.
  • name string (optional) Der Name der Location.
  • address string (optional) Die Adresse der Location. Diese sollte aussagekräftig und menschlich auffindbar sein.
  • lat float (optional) Der Breitengrad der Location.
  • lng float (optional) Der Längengrad der Location.
  • text string (optional) Eine Beschreibung der Location.
  • url string (optional) Eine Webseite mit weiteren Informationen zur Location.
  • image string (optional) Eine URL zu einem Bild.
  • categories array (optional) Ein Array aus Kategorie-IDs zu denen die Location gehört.
  • festivals string (optional) Ein Array aus Festival-IDs zu denen die Location gehört.
  • tags string (optional) Ein beliebig nutzbares Zeichenkettenfeld.
  • visible bool (optional) Wenn visible false ist, wird die Location nicht öffentlich angezeigt. Der Standardwert ist true.

Returns: Die geänderte Location im Erfolgsfall, sonst einen Statuscode 404.