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.

Authentifizierung

Infos über Authentifizierung, Status Codes und Code Beispiele

Endpunkte

Aktuell stehen folgende Endpunkte zur Verfügung:

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

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

KeyTyp bzw. Wert
filter.status„NOTED“ | „REQUESTED“ | „OPTIONED1“ | „OPTIONED2“ | „OPTIONED3“ | „CONFIRMED“ | „POSTPONED“ | „DONE“ | „CANCELLED“ | „BLOCKED“
filter.mainView„event“ | „rental“
filter.promotionType„1homepage“ | „2highlight“
filter.roomsKommagetrennte Liste von Raum-IDs
filter.searchBlockedRooms„true“ | „false“ (default: „true“)
Greift in Verbindung mit filter.rooms, ob geblockte Räume berücksichtigt werden sollen
filter.eventSuchtext für Event, Eventtyp, Künstler:in und Kontakt
filter.artistID 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
KeyTyp bzw. Wert
filter.date.kind„absolute“
filter.date.startDatum im Format „yyyy-MM-dd“ (z.B. „2022-03-01“)
filter.date.endDatum im Format „yyyy-MM-dd“
Relativ
KeyTyp bzw. Wert
filter.date.kind„relativeRange“
filter.date.startDayOffsetDifferenz in Tagen zu heute
Default: 0
filter.date.endDayOffsetDifferenz in Tagen zu heute
Default: unbegrenzt

Pagination

KeyTyp bzw. Wert
pagination.takeMaximale Anzahl zurückgegebener Events pro Aufruf
Default: 100
pagination.skipZu überspringende Events
Default: 0

Sortierung

KeyTyp 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?: {
    id: string
    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?: {
      id: string
      name: string
      images?: EventExportPayloadImage[]
      files?: EventExportPayloadFile[]
    }[]
    blockedRooms?: {
      id: string
      name: string
      images?: ExportPayloadImage[]
      files?: ExportPayloadFile[]
    }[]
  }[]
  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"