read-api: events

Mittels read-api können Events via HTTP abgerufen werden, um sie beispielsweise programmatisch auf einer Webseite auszuspielen oder auch eine Integration mit einem externen System herzustellen.

Aktuell stehen folgende Endpunkte zur Verfügung:

• GET /events (zur Abfrage einer Liste an Events)
• GET /event/:slug (zur Abfrage eines einzelnen Events)

Authentifizierung

Um die read-api zu nutzen, muss für einen User ein Access Token erzeugt werden.

Der Access Token muss im Header des Requests als Bearer Token übergeben werden. Die in den Beispielen angegebene Instanz-ID „demo“ bitte entsprechend ersetzen.

curl -i https://copilot.events/demo/api/events \
  -H "Authorization: Bearer mytoken123"

Status Codes

Folgende HTTP Status Codes können zurückgegeben werden:

Status Code	Anmerkung
200	OK (Erfolgreiche Abfrage)
400	Bad Request (Invalide Parameter)
401	Unauthorized (Invalider oder fehlender Access Token)
404	Not Found (Nicht gefundenes Event)
500	Internal Server Error (Unerwarteter Serverfehler)

GET /events

Zur Abfrage einer Liste an Events.

Parameter

Parameter für Filter, Pagination und Sortierung können im Query-String angegeben werden.

Hinweis: Für die Ausspielung auf die Webseite jedenfalls relevante Parameter sind hervorgehoben.

Event-Filter

Key	Typ bzw. Wert
filter.status	„NOTED“ | „REQUESTED“ | „OPTIONED1“ | „OPTIONED2“ | „OPTIONED3“ | „CONFIRMED“ | „POSTPONED“ | „DONE“ | „CANCELLED“ | „BLOCKED“
filter.mainView	„event“ | „rental“
filter.promotionType	„1homepage“ | „2highlight“
filter.rooms	Kommagetrennte Liste von Raum-IDs
filter.event	Suchtext für Event, Eventtyp, Künstler:in und Kontakt
filter.artist	ID eines/r beteiligten Künstler:in
filter.date.kind	„absolute“ | „relativeRange“ (s. unten) Default: „relativeRange“

Datums-Filter

Anm.: Es wird der Tagesanfang des Startzeitpunkts und das Tagesende des Endzeitpunkts mit dem Produktionszeitraum bzw. dem Beginn des Events verglichen.

Absolut

Key	Typ bzw. Wert
filter.date.kind	„absolute“
filter.date.start	Datum im Format „yyyy-MM-dd“ (z.B. „2022-03-01“)
filter.date.end	Datum im Format „yyyy-MM-dd“

Relativ

Key	Typ bzw. Wert
filter.date.kind	„relativeRange“
filter.date.startDayOffset	Differenz in Tagen zu heute Default: 0
filter.date.endDayOffset	Differenz in Tagen zu heute Default: unbegrenzt

Pagination

Key	Typ bzw. Wert
pagination.take	Maximale Anzahl zurückgegebener Events pro Aufruf Default: 100
pagination.skip	Zu überspringende Events Default: 0

Sortierung

Key	Typ bzw. Wert
sort.column	„status“ | „eventType“ | „start“ | „rooms“ Default: „start“
sort.direction	„asc“ | „desc“ Default: „asc“

Response Payload

Daten werden als Content-Type: application/json ausgegeben. Der genaue Typ eines Events (`EventExportPayload`) findet sich im Abschnitt „Event Payload“.

type ResponseBody =
  | {
      total: number
      data: EventExportPayload[]
      _links: {
        prev?: string
        current: string
        next?: string
      }
    }
  | {
      error: {
        code: string
        message: string
        data?: any
      }
    }

GET /event/:slug

Zur Abfrage eines einzelnen Events.

Response Payload

Daten werden als Content-Type: application/json ausgegeben. Der genaue Typ eines Events (`EventExportPayload`) findet sich im Abschnitt „Event Payload“.

type ResponseBody =
  | EventExportPayload
  | {
      error: {
        code: string
        message: string
        data?: any
      }
    }

Event Payload

export interface EventExportPayload {
  slug: string
  status: string
  optionEnd?: Date
  kind: string
  start: Date
  name: string
  subTitle?: string
  eventType: string
  memo?: string
  createdAt: Date
  updatedAt: Date
  displayNames: {
    eventTitleWithArtists: string
    eventTitleWithArtistsAndShows: string
    artists: string
    artistsAndShows: string
    rooms: string
    locationsWithRooms: string
    locationsWithCityAndRooms: string
  }
  activePromotions: { name: string }[]
  images?: EventExportPayloadImage[]
  files?: EventExportPayloadFile[]
  links?: EventExportPayloadLink[]
  locations?: {
    name: string
    address: {
      street: string
      addStreet: string
      zip: string
      city: string
      country: string
      lat: string
      lng: string
    }
    operator?: {
      displayName: string
      email: string
      phone: string
    }
    rooms?: {
      name: string
      images?: EventExportPayloadImage[]
      files?: EventExportPayloadFile[]
    }[]
  }[]
  artists?: {
    name: string
    description: string
    show?: {
      slug: string
      name: string
      releasesAt?: Date
      memo?: string
      images?: EventExportPayloadImage[]
      files?: EventExportPayloadFile[]
      artistShowInformations?: (
        | {
            name: string
            value: string
            tags: string[]
          }
        | undefined
      )[]
    }
    contacts?: {
      role: string
      displayName: string
      email: string
      phone: string
    }[]
    images?: EventExportPayloadImage[]
    files?: EventExportPayloadFile[]
    links?: EventExportPayloadLink[]
    artistInformations?: (
      | {
          name: string
          value: string
          tags: string[]
        }
      | undefined
    )[]
  }[]
  contacts?: {
    role: string
    displayName: string
    email: string
    phone: string
  }[]
  schedule?: {
    name: string
    date: Date
    memo: string
  }[]
  eventInformations?: (
    | {
        name: string
        value: string
        tags: string[]
      }
    | undefined
  )[]
  offersOnEvent?: {
    offerStatus: string
    name: string
    description: string
    discount: number
    roomsOnOffer?: {
      room: string
      description: string
      price: number
      discount: number
      vat: number
    }[]
    resourcesOnOffer?: {
      resource: string
      description: string
      amount: number
      unit: string
      price: number
      discount: number
      vat: number
    }[]
  }[]
  ticketing?: {
    ticketOffice: string
    category: string
    contingent: number
    vat: number
    netPrice: number  // Nettopreis in cent
    grossPrice: number  // Bruttopreis in cent
    timestamp: Date
    soldTickets: number
    saleTotal: number
  }[]
  shopEvent?: {
    start: Date
    name: string
    subTitle?: string
    description?: string
    location?: string
    image?: ExportPayloadImage
    url?: string
  }
}

type EventExportPayloadImage = {
  name: string
  description: string
  tags: string[]
  sizes: Record<string, string>
}

type EventExportPayloadFile = {
  name: string
  description: string
  path: string
  preview: string
  download: string
  tags: string[]
}

type EventExportPayloadLink = {
  type: string
  value: string
}

Datum & Uhrzeit

Alle Werte mit Typ Date werden als ISO 8601 Date String in UTC ausgegeben (z.B. „2022-05-26T19:00:00.000Z“). Für die Darstellung ist entsprechend eine Umwandlung in die lokale Zeitzone erforderlich.

Bilder

Jedes Bild wird mit den folgenden Informationen und Bildgrößen ausgespielt.

name: 
description: string
sizes: [640, 750, 828, 1080, 1200, 1920, 2048, 3840]

Promotions

Für Events kann eine Homepage oder Highlight Promotion aktiviert werden:

Die Promotions lassen sich über den Query Parameter „promotionType“ filtern.

Standardmäßig gibt es nur die Promotions „1homepage“ und „2highlight“. Sofern ihr andere benötigt, meldet euch.

Ist kein promotionType im Query-String angegeben, findet diesbezüglich keinerlei Einschränkung statt.

Dateien

Sollen Dateien oder Bilder mit ausgespielt werden, müssen diese auf öffentlich gesetzt werden. Vertrauliche Dateien und Bilder werden nicht ausgespielt.

Beispiele

Die ersten 50 Events mit Promotion „1homepage“:

curl -i https://copilot.events/demo/api/events?filter.promotionType=1homepage&pagination.take=50&pagination.skip=0 \
  -H "Authorization: Bearer mytoken123"

Die ersten 100 Events (= Default) mit Promotion „2highlight“:

curl -i https://copilot.events/demo/api/events?filter.promotionType=2highlight \
  -H "Authorization: Bearer mytoken123"

Einzelnes Event:

curl -i https://copilot.events/demo/api/event/20221222_rockkonzert \
  -H "Authorization: Bearer mytoken123"