Eventkrake 3 REST API

In the third version of the eventkrake the central server isn’t needed anymore to spread the data. Instead the plugin gives direct read-only access via the built-in WordPress REST API. The url to the data is based on your wordpress installation. For this documentation we asume https://eventrake.de as „our“ wordpress.

How to access the API?

You need the url of your WordPress plus the following to access the API: /wp-json/eventkrake/v3 and after this you add the command (e.g. /events). So a full request would be like:
https://eventkrake.de/wp-json/eventkrake/v3/events

Parameters are added to the URL like the well known URL parameters: A questions mark on the beginning, the parameter name, the parameter value and an ampersand to seperate parameters. A full request width parameters included will look like:
https://eventkrake.de/wp-json/eventkrake/v3/events?earliestStart=2020-03-31T08:00:00&latestStart=2020-03-31T19:00:00

What will we get back?

The API returns a JSON object with three arrays: events, locations, artists. These three arrays holds all your data. If you requested some events, your will get the locations and artists belonging to this events. If you request some artists, your also get the events to the artists and the locations to the events. And if you request some locations, you get the events and the artists in this location.

Commands and Parameters

/events

  • earliestStart
    • Gives a minimal date for the events. This parameter is checked against the start of an event.
  • latestStart
    • Gives a maximal date for the events. This parameter is checked against the start of an event.
  • earliestEnd
    • Gives a minimal date for the events. This parameter is checked against the end of an event.
  • latestEnd
    • Gives a maximal date for the events. This parameter is checked against the end of an event.

/locations

There are no parameters yet.

/artists

There are no parameters yet.

 

This part is only for historical reasons and will be removed somewhen, even if the old eventkrake API will be accessible for some time.

(deprecated) 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 https://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 derzeit laufenden 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.