API docs by Redocly

Use Case 3 - API (v2)

Download OpenAPI specification:Download

E-mail: retzlaff@buehnenverein.de

WIP: This document is a work in progress. The API documented here is subject to change and should not be widely adopted yet.

This document describes the public API implemented by theaters to provide their current repertoire. The data structure is based on schema.org types, in particular CreativeWork and Event.

This document is intended as documentation for consumers of the API as well as anyone who intends to implement an API endpoint that is compatible with Use Case 3.

Notes for API implementors

  • It's not required to use the same endpoint name as documented here. The important part is to implement a single endpoint that returns data in the format declared in this specification.
  • You can test whether your implementation matches this specification using our custom validation page

events

Endpoint providing public information about upcoming events

Provides public information about events

TODO: Write description

Responses

Response Schema: application/ld+json
@context
required
string
Value: "https://schema.org"
version
required
string
Value: "v2"

The API version that is being used. MUST be the string "v2" for now.

required
object (Organization)
@type
required
string
Value: "Organization"
name
required
string

The organization's name

object (PostalAddress)

The address of e.g. an organization or event location.

@type
required
string
Value: "PostalAddress"
postalCode
required
string

The postal code.

streetAddress
string

The street address.

addressLocality
required
string

The locality in which the street address is, i.e. the city.

addressCountry
string

The country of this address.

logo
string <uri>

A link to the organization's logo.

required
Array of objects (Production)

A list of all current productions in the repertoire.

Array
@type
required
string (CommonCreativeWorkType)
Enum: "CreativeWork" "Play"
identifier
required
string

The unique ID of this production. This could be an internal database ID, for example.

required
StringType (string) or InternationalizedString (object)

The production's title.

StringType (string) or InternationalizedString (object)

The production's optional subtitle.

StringType (string) or InternationalizedString (object)

A text describing the production.

StringType (string) or InternationalizedString (object)

A short abstract or teaser text describing the production.

object (OriginalWork)

An object describing the work that this production is based on (if any). E.g. this could describe the original dramatic text that was used as the basis of a theater production.

required
Array of objects (Event)

A list of events at which this production will be performed.

genre
Array of strings
Items Enum: "audiowalk" "ballett" "comedy" "digitaltheater" "figurentheater" "game-theater" "improtheater" "inklusives-theater" "installation" "kabarett" "kammerkonzert" "konzert" "lecture-performance" "lesung" "live-hoerspiel" "musical" "musiktheater" "objekttheater" "oper" "operette" "performance" "physical-theatre" "postmigrantisches-theater" "puppentheater" "sinfoniekonzert" "sprechtheater" "szenische-lesung" "szenisches-konzert" "tanz" "theater-im-oeffentlichen-raum" "workshop" "zeitgenoessischer-tanz"

The genre of this production. Must use one of the pre-defined values.

productionType
string
Enum: "WorldPremiere" "FirstPerformance" "LanguagePremiere" "LocalPremiere" "CountryPremiere" "Revival"

A value that indicates special characteristics of this production:

  • WorldPremiere: This is the first time that this creative work is publicly performed anywhere in the world.
  • FirstPerformance: This is the first time that this creative work is publicly performed in a specific context. E.g. it could be a language premiere, country premiere, or local premiere.
  • Revival: A new production (restaging) of an existing play or similar creative work.
  • LanguagePremiere:The first performance of a play or similar creative work in a particular language.
  • LocalPremiere: The first performance of a play or similar creative work in a particular local area.
  • CountryPremiere: The first performance of a play or similar creative work in a particular country.
accessibilityHazard
Array of strings
Items Enum: "none" "unknown" "flashingHazard" "motionSimulationHazard" "soundHazard" "noFlashingHazard" "noMotionSimulationHazard" "noSoundHazard" "unknownFlashingHazard" "unknownMotionSimulationHazard" "unknownSoundHazard"

A list of characteristics of the production that may be physiologically dangerous to some users.

accessibilitySummary
string

A human-readable summary of specific accessibility features or deficiencies of the production.

Array of StringType (string) or InternationalizedString (object)

A list of content warnings, i.e. warnings about contents of this production that may be distressing or triggering to some people.

inLanguage
Array of strings

Primary language(s) of this production. Should contain a BCP 47 Language Tag.

object (Audience)

Object describing the intended target audience of this production.

Array of objects (CreatorRole)

List of people and organizations that contributed to the creation of this production, e.g. directors, stage designers, musical directors, etc. If this production is a collaboration with another organization, e.g. another theater or orchestra, this organization should also be included in this field.

If multiple people perform the same role/function (e.g. there is multiple directors), each person should get their own entry in the creator array.

StringType (string) or InternationalizedString (object)

Text that can be used to credit persons and/or organizations that are associated with this production. This field can be used to include a text snippet on, e.g., funding organizations that needs to be included on platforms advertising the production.

Array of Person (object) or Organization (object) (PersonOrOrganization)

A list of organization's that support this production through some kind of financial contribution.

Array of Person (object) or Organization (object) (PersonOrOrganization)

A list of organization's that support this production through a pledge, promise, or financial contribution.

Response samples

Content type
application/ld+json
{
  • "@context": "https://schema.org",
  • "version": "v2",
  • "organization": {
    • "@type": "Organization",
    • "name": "Staatstheater Augsburg",
    • "address": {
      },
    • "logo": "http://example.com"
    },
  • "productions": [
    • {
      }
    ]
}