Preparation

The use of the go~mus public API does not require authentication and no API key.

See detailed documentation on Reseller API on how to create orders and sell end customer stuff like tickets, events and tours.

Museums

Provides information about the online bookable museums

List of museums

GET https://demo.gomus.de/api/v4/museums

curl "https://demo.gomus.de/api/v4/museums"

{
    "museums": [
        {
        "id": 1,
        "title": "Intro Museum",
        "sub_title": "Moderne Kunst des 21. Jahrhunderts",
        "picture": {
            "title": null,
            "description": null,
            "copyright_info": null,
            "teaser": "../teaser/hintergrund_grau.jpg",
            "preview": "../preview/hintergrund_grau.jpg",
            "article": "../article/hintergrund_grau.jpg",
            "detail": "../detail/hintergrund_grau.jpg"
            }
        },
        {
            ...
        }
    ],
    "meta": {
        "total_count": 1,
        "page": 1,
        "per_page": 25
    }

}

Available filters:

a simple search is available with the q parameter, e.g. ?q=Modern, see more in the search section
locales are available with the locale parameter, see more in the locale section

Available parameters:

per_page, defaults to system default (25)
page, defaults to 1

Response

The JSON response contains a list of museums as an array and a meta block.

id (integer), the unique database id of the museum
title (string), the name of the museum
sub_title (string), a more descriptive name
picture, contains picture information and urls for various image formats

Details of a single museum

GET https://demo.gomus.de/api/v4/museums/:id

curl "https://demo.gomus.de/api/v4/museums/1"

{
    "museum": {
        "id": 1,
        "title": "Alte Nationalgalerie",
        "sub_title": "Kunst des 19. Jahrhunderts ",
        "description": null,
        "picture": {
            "title": null,
            "description": null,
            "copyright_info": null,
            "teaser": "../teaser/hintergrund_grau.jpg",
            "preview": "../preview/hintergrund_grau.jpg",
            "article": "../article/hintergrund_grau.jpg",
            "detail": "../detail/hintergrund_grau.jpg"
        },
        "content": {
            ...
        },
        "location": {
            "name": "Alte Nationalgalerie",
            "city": "Berlin",
            "country": "Deutschland",
            "street": "Bodestrasse",
            "zip": "10178",
            "latitude": 52.5197,
            "longitude": 13.3985
        }
    }
}

Response

The JSON response contains a museum block with information for that museum. The information is the same as that of the museums list response, but with the addition of a location block.

location, contains information about the location of the museum.
content, contains key/value pairs of custom defined attributes, e.g. the following:

"content": {
    "cms_title": "Museum",
    "cms_description": "Das Museum!",
    "shop_title": "Museum",
    "shop_description": "Das Museum lädt ein.",
    "picture_title": "",
    "picture_description": "",
    "picture_copyright_info": ""
}

Opening hours of a single museum

GET https://demo.gomus.de/api/v4/museums/:id/opening_hours

curl "https://demo.gomus.de/api/v4/museums/1/opening_hours?date=2016-12-31"

{
    "opening_hours": {
        "begin": "2016-12-31T10:00:00+01:00",
        "end": "2016-12-31T18:30:00+01:00",
    }
}

Available parameters:

date, defaults to today

Response

The JSON response contains the begin and end of the opening hours as datetimes.

Exhibitions

Provides information about the online bookable exhibitions

List of exhibitions

GET https://demo.gomus.de/api/v4/exhibitions

curl "https://demo.gomus.de/api/v4/exhibitions"

{
    "exhibitions": [
        {
            "id": 33,
            "museum_id": 20,
            "title": "Dauerausstellung | Gemäldegalerie",
            "sub_title": "Malerei vom 13. bis zum 18. Jahrhundert ",
            "slider_description": "Malerei vom 13. bis zum 18. Jahrhundert",
            "featured": true,
            "picture": {
                "title": null,
                "description": null,
                "copyright_info": null,
                "teaser": "...",
                "preview": "../preview/hintergrund_grau.jpg",
                "article": "../article/hintergrund_grau.jpg",
                "detail": "../detail/hintergrund_grau.jpg"
            },
            "time_frames": [
                {
                "start_at": "2016-11-28T09:00:00+01:00",
                "end_at": "2016-12-04T20:45:00+01:00"
                }
            ]
        },
        {
            ...
        }
    ],
    "meta": {
        "total_count": 1,
        "page": 1,
        "per_page": 25
    }

}

Available filters:

a simple search is available with the q parameter, e.g. ?q=Modern, see more in the search section
locales are available with the locale parameter, see more in the locale section
by_museum_ids (Array of museum ids), filter by museums, see museums section
by_featured (Boolean, true|false), filter by featured flag

Available parameters:

per_page, defaults to system default (25)
page, defaults to 1

Response

The JSON response contains a list of exhibitions as an array and a meta block.

id (integer), the unique database id of the exhibition
museum_id (integer), the unique database id of the museum to which the exhibition belongs
title (string), the name of the exhibition
sub_title (string), a more descriptive name
picture, contains picture information and urls for various image formats
slider_description, additional description field used by the online shop slider
featured, boolean flag of whether the exhibition is featured or not
time_frames, array of hashes with start_at and end_at key/value pairs for retention times of exhibitions. An exhibition without any timeframes is permanent exhibition.

Details of a single exhibition

GET https://demo.gomus.de/api/v4/exhibitions/:id

curl "https://demo.gomus.de/api/v4/exhibitions/1"

{
    "exhibition": {
        "id": 33,
        "museum_id": 20,
        "title": "Dauerausstellung | Gemäldegalerie",
        "sub_title": "Malerei vom 13. bis zum 18. Jahrhundert ",
        "slider_description": "Malerei vom 13. bis zum 18. Jahrhundert",
        "description": "...",
        "featured": true,
        "picture": {
            "title": null,
            "description": null,
            "copyright_info": null,
            "teaser": "../teaser/hintergrund_grau.jpg",
            "preview": "../preview/hintergrund_grau.jpg",
            "article": "../article/hintergrund_grau.jpg",
            "detail": "../detail/hintergrund_grau.jpg"
        },
        "time_frames": [
            {
            "start_at": "2016-11-28T09:00:00+01:00",
            "end_at": "2016-12-04T20:45:00+01:00"
            }
        ],
        "content": {
            ...
        },
        "location": {
            "name": "Gemäldegalerie",
            "city": "Berlin",
            "country": "Deutschland",
            "street": "Matthäikirchplatz",
            "zip": "10785",
            "latitude": 52.5082,
            "longitude": 13.3673
        }
    }
}

Response

The JSON response contains an exhibition block with information for that exhibition. The information is the same as that of the exhibitions list response, but with the addition of a location block.

location, contains information about the location of the exhibition.
content, contains key/value pairs of custom defined attributes, e.g. the following:

"content": {
    "cms_title": "Museum Besuchertage",
    "cms_sub_title": "",
    "cms_description": "Das Museum lädt ein.",
    "shop_title": "Museum Besuchertage",
    "shop_sub_title": "",
    "shop_description": "Das Museum lädt ein.",
    "picture_title": "",
    "picture_description": "",
    "picture_copyright_info": ""
}

Tickets

Provides information about the online bookable tickets

List of tickets

GET https://demo.gomus.de/api/v4/tickets

curl "https://demo.gomus.de/api/v4/tickets"

{
  "tickets": [
    {
      "id": 247,
      "title": "El Siglo de Oro mit Gemäldegalerie regulär",
      "ticket_type": "time_slot",
      "bookable": true,
      "museum_ids": [20],
      "exhibition_ids": [2057, 33],
      "price_cents": 1400,
      "discount": 0,
      "vat_pct": 0,
      "tax_included": true,
      "entry_duration": 30,
      "min_persons": 0,
      "max_persons": 100,
      "quota_ids": [19],
      "first_entry": 660,
      "last_entry": 990,
      "personalizeable": false,
      "attendees": "required",
      "identification": false
    }
  ],
  "meta": {
    "total_count": 1,
    "page": 1,
    "per_page": 25
  }
}

Available filters:

a simple search is available with the q parameter, e.g. ?q=Modern, see more in the search section
locales are available with the locale parameter, see more in the locale section
by_ticket_ids (Array of ticket ids), filter by specific tickets
by_museum_ids (Array of museum ids), filter by museums, see museums section
by_exhibition_ids (Array of exhibition ids), filter by exhibitions, see exhibitions section
by_bookable (Boolean, true|false, default: all), filter by general bookability for current account (or public)
by_ticket_type, (String) (annual, time_slot, normal, default: all but annual)
by_ticket_types, (Array of annual, time_slot, normal, default: all but annual)

Available parameters:

valid_at (YYYY-MM-DD), defaults to today
per_page, defaults to system default (25)
page, defaults to 1

Response

The JSON response contains a list of tickets as an array and a meta block.

id (integer), the unique database id of the ticket
title (string), the name of the ticket
description (text), a more descriptive name
ticket_type, either "day_ticket" or "time_slot"
bookable (boolean), if the ticket is bookable within your authentication type
museum_ids, array of museum ids to which the ticket belongs, can be empty
exhibition_ids, array of exhibition ids to whick the ticket belongs, can be empty
quota_ids, array of quota ids to which the ticket belongs, can be empty
price_cents (integer), price of the ticket in EUR cents
discount (integer), discount in percent (0-100) to apply on total price for this item if ordered
vat_pct (float), the tickets tax rate
tax_included (boolean), whether the tax (if any) is included in price_cents or not
first_entry (integer), first possible entry in minutes from beginning of day, can be combined with valid_at parameter
last_entry (integer), last possible entry in minutes from beginning of day, can be combined with valid_at parameter
entry_duration (integer), if ticket type is a time slot, the slot duration in minutes, else null
min_persons (integer), minimum quantity to buy per order
max_persons (integer), maximum quantity to buy per order
personalizeable (boolean), weather the ticket can be personalised (e.g. annual tickets)
attendees (string), when required, the attendees needs to be set on purchase
identification (string), info attribute for entry system to require manual identification document (e.g. for reduced tickets)

Details of single ticket

GET https://demo.gomus.de/api/v4/tickets/:id

curl "https://demo.gomus.de/api/v4/tickets/1"

{
  "ticket": {
    "id": 247,
    "title": "El Siglo de Oro mit Gemäldegalerie regulär",
    "sub_title": null,
    "description": "...",
    "ticket_type": "time_slot",
    "bookable": true,
    "museum_ids": [20],
    "exhibition_ids": [2057, 33],
    "quota_ids": [19],
    "price_cents": 1400,
    "vat_pct": 0,
    "discount": 0,
    "tax_included": true,
    "first_entry": 660,
    "last_entry": 990,
    "entry_duration": 30,
    "min_persons": 0,
    "max_persons": 100,
    "after_sale_information": null,
    "content": {
      "shop_title": "Best ticket in the world",
      "shop_sub_title": "",
      "shop_description": ""
    },
    "personalizeable": false,
    "attendees": "required",
    "identification": false,
    "location": {
      "name": "Gemäldegalerie",
      "city": "Berlin",
      "country": "Deutschland",
      "street": "Matthäikirchplatz",
      "zip": "10785",
      "latitude": 52.5082,
      "longitude": 13.3673
    }
  }
}

Available parameters:

valid_at (YYYY-MM-DD), defaults to today

Response

The JSON response contains a ticket block with information for that the information is the same as that of the tickets list response, but with the addition of a couple of keys.

after_sale_information (string), information to be shown after the sale of a ticket. Can contain html elements.
location, contains information about the location of the museum that the ticket belongs to.
content contains dynamic multi locale information

NOTE: for information on combined/sub-tickets, please see the Pergamon + Panorama example

Capacities of a ticket

A ticket has one or more capacities. Each capacity is the maximum bookable quantity of the ticket for a specific range of time.

GET https://demo.gomus.de/api/v4/tickets/:id/capacity

curl "https://demo.gomus.de/api/v4/tickets/1/capacity"

{
  "data": {
    "2016-07-06T11:00:00+02:00": 15,
    "2016-07-06T11:30:00+02:00": 21,
    "2016-07-06T12:00:00+02:00": 16,
    "2016-07-06T12:30:00+02:00": 21,
    "2016-07-06T13:00:00+02:00": 21,
    "2016-07-06T13:30:00+02:00": 21,
    "2016-07-06T14:00:00+02:00": 20,
    "2016-07-06T14:30:00+02:00": 21,
    "2016-07-06T15:00:00+02:00": 21,
    "2016-07-06T15:30:00+02:00": 21,
    "2016-07-06T16:00:00+02:00": 21
  }
}

Using the JSON response on the right as an example, between 11.00 and 11.30 on the 6th July 2016, the maximum bookable quantity is 15. If only one available time slot is returned, as is the case for day tickets, the time range is up untill the end of the day.

Available parameters:

date (YYYY-MM-DD), defaults to today
reservations, defaults to none

Response

The JSON response contains a data block of available time slots and capacities as a hash (key/value pairs). For day tickets, the first possible entry will be returned.

The capacity check takes all quotas that the ticket belongs to into account. Zero values are not returned.

Reservations

Provide an array of reservation tokens to be considered in calculation

Calendar - for tickets

The ticket calender contains information about the generic bookablility of tickets - a very fast and easy way to detect if there is anything bookable in a larger timeframe.

GET https://demo.gomus.de/api/v4/tickets/calendar

curl "https://demo.gomus.de/api/v4/tickets/calendar"

{
  "data": {
    "2016-05-27": false,
    "2016-05-28": false,
    "2016-05-29": false,
    "2016-05-30": true,
    "2016-05-31": true
  }
}

{
  "data": {
    "2016-07-06": [
      {
        "quota": {
          "id": 3,
          "tickets": [261, 262, 263, 264, 265, 266],
          "capacities": [
            {
              "2016-07-06 11:00:00 +0200": 100
            }
          ]
        }
      }
    ]
  }
}

Available filters:

by_ticket_ids (Array of ticket ids), filter by specific tickets
by_museum_ids (Array of museum ids), filter by museums, see museums section
by_exhibition_ids (Array of exhibition ids), filter by exhibitions, see exhibitions section
by_bookable (Boolean, true|false, default: all), filter by general bookability for current account (or public)
by_ticket_type, (String) (annual, time_slot, normal, default: all but annual)
by_ticket_types, (Array of annual, time_slot, normal, default: all but annual)

Available parameters:

start_at (YYYY-MM-DD), defaults to today
end_at (YYYY-MM-DD), defaults to end of month
depth: string, one of any|all, defaults to any
reservations, array of reservations made before, defaults to none

Response

The depth parameter defines the depth of search and the amount of detail in the result. On any the search will quit the loop for each day as soon as a bookable ticket is found and will provide a boolean (true or false) for the bookability as the result. This is a lot faster than the all mode, where the result is an array of quota objects and the relevant capacity information.

The maximum time frame is 31 days.

Reservations

Provide an array of reservation tokens to be considered in calculation

Capacities for a set of tickets

A ticket has one or more capacities. Each capacity is the maximum bookable quantity of the ticket for a specific range of time.

GET https://demo.gomus.de/api/v4/tickets/capacities

curl "https://demo.gomus.de/api/v4/tickets/capacities"

{
  "data": {
    "19": {
      "tickets": [247, 248],
      "capacities": {
        "2016-07-06T16:15:00+02:00": 30,
        "2016-07-06T16:20:00+02:00": 30,
        "2016-07-06T16:25:00+02:00": 30,
        "2016-07-06T16:30:00+02:00": 0
      }
    },
    "20": {
      "tickets": [248],
      "capacities": {
        "2016-07-06T16:15:00+02:00": 15,
        "2016-07-06T16:20:00+02:00": 15,
        "2016-07-06T16:25:00+02:00": 15,
        "2016-07-06T16:30:00+02:00": 0
      }
    }
  }
}

Tickets are assigned to (one or multiple) quotas and reduce each others capacity when ordered. As a result, capacity calculation becomes a little more complicated.

For a single ticket the capacities are calculated for you, see the capacities of a ticket section above. For multiple tickets however, to avoid requesting new capacities for each quantity update, we provide the quota ids so that the new ticket capacities can be calculated in the browser.

For example, if two tickets reside in the same quota which has a capacity of 10 for a specific time, if 2 of one ticket is selected only 8 are available for the other.

Note that for a set of tickets with each different entry durations the greatest common divisor of all entry durations is used as step size for the capacity time slots. If this is the case, you need to ensure you set the time for the ticket to a valid value (first_entry + n * entry_duration). For day tickets you need to set first_entry as time of booking.

Distinguishing unavailable and sold out tickets.

An array of total capacities is returned that reflect the total configured capacity for a timeslot ignoring any sales. This information can be used to determine whether a ticket was available but is sold out or whether a ticket did not have any capacity in the first place.

{
  "data": {
    "19": {
      "tickets": [247, 248],
      "capacities": {
        "2016-07-06T16:15:00+02:00": 0,
        "2016-07-06T16:20:00+02:00": 0,
        "2016-07-06T16:25:00+02:00": 0,
        "2016-07-06T16:30:00+02:00": 0
      },
      "total_capacities": {
        "2016-07-06T16:15:00+02:00": 30,
        "2016-07-06T16:20:00+02:00": 30,
        "2016-07-06T16:25:00+02:00": 30,
        "2016-07-06T16:30:00+02:00": 30
      }
    }
  }
}

In general tickets that do not have a defined total capacity can be excluded from display.

Necessary parameters:

ticket_ids (Array of ticket ids)

Available parameters:

date (YYYY-MM-DD), defaults to today
reservations, array of reservations made before, defaults to none

Response

The response is a data block, which contains a hash with quota ids as keys, a list of ticket ids affected by the quota (as a subset of the query) and a list of (still available) capacities as well as the total capacities.

Note that the ticket response block may not contain all of your requested ticket ids. It only contains tickets bookable for your current user.

Reservations

Provide an array of reservation tokens to be considered in calculation

Contents for a set of tickets

This call returns dynamic content for a set of tickets. Use this to optimise content fetching.

GET https://demo.gomus.de/api/v4/tickets/content

curl "https://demo.gomus.de/api/v4/tickets/content?ticket_ids[]=14&ticket_ids[]=11"

{
  "data": [
    {
      "id": 11,
      "content": {
        "shop_title": "My Ticket Title"
      }
    },
    {
      "id": 14,
      "content": {
        "shop_title": "Another Ticket Title",
        "shop_description": "<p>Description DE</p>"
      }
    }
  ],
  "meta": {
    "total_count": 2,
    "page": 1,
    "per_page": 25
  }
}

Available filters:

locales are available with the locale parameter, see more in the locale section

Necessary parameters:

ticket_ids (Array of ticket ids)

Available parameters:

attr, defaults to nil, can be used to only query a specific attribute per set
per_page, defaults to system default (25)
page, defaults to 1

Response

The JSON response contains a list of contents for a set of tickets as an array and a meta block.

content, contains key/value pairs of a specific attribute per set of tickets

Events

Provides information about the online bookable events and dates.

Event categories

GET https://demo.gomus.de/api/v4/events/categories

curl "https://demo.gomus.de/api/v4/events/categories"

{
  "categories": [
    {
      "id": 3,
      "name": "öffentliche Führung"
    },
    {
      "id": 4,
      "name": "Kurs / Workshop"
    },
    {
      "id": 5,
      "name": "Kinder / Familien"
    }
  ]
}

Response

The JSON response contains a list of all event categories to build up filters. Note: this only contains valid elements, some events might have no name set. Some categories have duplicate names.

Event languages

GET https://demo.gomus.de/api/v4/events/languages

curl "https://demo.gomus.de/api/v4/events/languages"

{
    "languages": [
        {
        "id": 1,
        "name": "Deutsch"
        },
        {
         "id": 2,
         "name": "Englisch"
        }
    ]
}

Response

The JSON response contains a list of all languages used by online bookable event products to build up filters.

Event tags

Events can be tagged with the following tag types:

Age groups

GET https://demo.gomus.de/api/v4/events/age_groups

curl "https://demo.gomus.de/api/v4/events/age_groups"

{
    "age_groups": [
        {
            "id": 1,
            "name": "Kinder bis 10 Jahre"
        },
        {
            "id": 2,
            "name": "Kinder ab 10 Jahre"
        }
    ]
}

Audiences

GET https://demo.gomus.de/api/v4/events/audiences

curl "https://demo.gomus.de/api/v4/events/audiences"

{
    "audiences": [
        {
            "id": 1,
            "name": "Jugendliche"
        },
        {
            "id": 2,
            "name": "Erwachsene"
        }
    ]
}

Catch words

GET https://demo.gomus.de/api/v4/events/catch_words

curl "https://demo.gomus.de/api/v4/events/catch_words"

{
    "catch_words": [
        {
            "id": 1,
            "name": "Ägypten"
        },
        {
            "id": 2,
            "name": "Mythologie"
        }
    ]
}

Proposal categories

GET https://demo.gomus.de/api/v4/events/proposal_categories

curl "https://demo.gomus.de/api/v4/events/proposal_categories"

{
    "proposal_categories": [
        {
            "id": 1,
            "name": "Schulklasse"
        },
        {
            "id": 2,
            "name": "Gruppe ohne Guide"
        }
    ]
}

Grades

GET https://demo.gomus.de/api/v4/events/grades

curl "https://demo.gomus.de/api/v4/events/grades"

{
    "grades": [
        {
            "id": 1,
            "name": "Grundschule Klasse 1"
        },
        {
            "id": 2,
            "name": "Grundschule Klasse 2"
        },
        {
            "id": 3,
            "name": "Sekundarstufe II"
        }
    ]
}

Tag responses

The JSON response contains a list of used event tags by category to build up filters.

List of events

GET https://demo.gomus.de/api/v4/events

curl "https://demo.gomus.de/api/v4/events"

{
    "events": [
        {
            "id": 101174,
            "exhibition_id": 2057,
            "museum_id": 20,
            "title": "El Siglo de Oro | Öffentliche Führung",
            "sub_title": "60 Minuten | 4 EUR zzg. Eintritt<br>Di – Fr / 16:00 Uhr, Sa und So / 14:30 und 16:00 Uhr<br>",
            "featured": false,
            "bookable": true,
            "registerable": true,
            "category": {
                "id": 3,
                "name": "öffentliche Führung"
            },
            "picture": {
                "title": null,
                "description": null,
                "copyright_info": null,
                "teaser": "../teaser/hintergrund_grau.jpg",
                "preview": "../preview/hintergrund_grau.jpg",
                "article": "../article/hintergrund_grau.jpg",
                "detail": "../detail/hintergrund_grau.jpg"
            },
            "location": {
                "name": "Gemäldegalerie",
                "city": "Berlin",
                "country": "Deutschland",
                "street": "Matthäikirchplatz",
                "zip": "10785",
                "latitude": 52.5082,
                "longitude": 13.3673
            },
            "age_groups": [],
            "audiences": [],
            "catch_words": [],
            "disablements": [],
            "grades": [],
            "proposal_categories": [],
            "languages": [
                {
                    "id": 1,
                    "name": "Deutsch"
                }
            ]
        }
    ],
    "meta": {
        "total_count": 1,
        "page": 1,
        "per_page": 25
    }

}

Available filters:

a simple search is available with the q parameter, e.g. ?q=Modern, see more in the search section
locales are available with the locale parameter, see more in the locale section
by_featured (Boolean, true|false), filter by featured flag
by_museum_ids (Array of museum ids), filter by museums, see museums section
by_exhibition_ids (Array of exhibition ids), filter by exhibitions, see exhibitions section
by_category_ids (Array of category ids), filter by category, see categories section
by_age_group_ids (Array of category ids), filter by category, see age group section
by_audience_ids (Array of category ids), filter by category, see audience section
by_catch_word_ids (Array of category ids), filter by category, see catch words section
by_disablement_ids (Array of category ids), filter by category, see disablements section
by_grade_ids (Array of category ids), filter by category, see grades section
by_proposal_category_ids (Array of category ids), filter by proposal category, see categories section
by_categories (Array of category names), filter by category names, see categories section
by_language_ids (Array of language ids), filter by language, see languages section
by_bookable (Boolean, true|false, default: all), filter by general bookability for current account (or public)
with_bookings_in_future (Boolean, true|false, default: all), filter events that have bookable dates in the future

Available parameters:

per_page, defaults to system default (25)
page, defaults to 1

Response

The JSON response contains a list of events as an array and a meta block.

id (integer), the unique database id of the event
title (string), the name of the event
sub_title (string), the sub title of the event
featured, boolean flag of whether the event is featured or not
bookable, boolean flag of whether the event is bookable in the current scope or not
registerable, boolean flag of whether the event is public registerable or not

plus blocks of attributes for category, picture, location and audiences.

Details of single event

GET https://demo.gomus.de/api/v4/events/:id

curl "https://demo.gomus.de/api/v4/events/1"

The information is the same as that of the events list response, but with the addition of the description key and dynamic contents. If event is registerable and an authenticatable user has the permission, this attribute contains a link to the public registration form.

Calendar for a single event

GET https://demo.gomus.de/api/v4/events/:id/calendar

curl "https://demo.gomus.de/api/v4/events/1/calendar"

Note: This route is obsolete. Please use api/v4/calendar?by_event_ids[]=:id

Dates for a single event

GET https://demo.gomus.de/api/v4/events/:id/dates

curl "https://demo.gomus.de/api/v4/events/1/dates"

{
    "dates": [
        {
            "id": 1065,
            "event_id": 10,
            "exhibition_id": null,
            "museum_id": 1,
            "category": {
              "id": 7,
              "name": "Öffentliche Führung",
              "filtername": ""
            },
            "bookable": true,
            "registerable": false,
            "title": "Termin #241",
            "sub_title": null,
            "start_time": "2017-12-03T13:00:00+01:00",
            "duration": 90,
            "seats": {
                "min": 1,
                "max": 30,
                "booked": 0,
                "available": 30,
                "max_per_registration": null
            },
            "language": {
              "id": 1,
              "name": "Deutsch"
            }
        }
    ],
    "meta": {
        "total_count": 1,
        "page": 1,
        "per_page": 25
    }
}

Queries the available dates for a specific event. The default shows only dates for today, or specified by the date parameter. A range of up to 31 days can be queried by using the start_at and end_at parameter.

Available filters:

by_language_ids (Array of language ids), filter by date language, see languages section
by_bookable (Boolean, true|false, default: all), filter by general bookability for current account (or public)

Available parameters:

date (YYYY-MM-DD), defaults to today
start_at (YYYY-MM-DD), instead of date
end_at (YYYY-MM-DD), instead of date
per_page, defaults to system default (25)
page, defaults to 1

Response

The JSON response contains a list of dates as an array and a meta block.

id (integer), the unique database id of the events’ date
event_id (integer), the unique database id of the parent event
exhibition_id (integer), the unique database id of the parent events’ exhibition
museum_id (integer), the unique database id of the parent events’ museum
title (string), the name of the date
sub_title (string), the sub title of the date
start_time (iso8601), the date’s timestamp
language, with id and name
bookable, boolean flag of whether the event is bookable in the current scope or not
registerable, boolean flag of whether the event is public registerable or not
seats, further information for available seats. max_per_registration indicates the limit for seats per order

Details for a single date

GET https://demo.gomus.de/api/v4/events/:event_id/dates/:id

curl "https://demo.gomus.de/api/v4/events/1/dates/1"

{
    "date": {
        "id": 22974,
        "event_id": 101174,
        "exhibition_id": 2057,
        "museum_id": 20,
        "category": {
            "id": 23,
            "name": "öffentliche Führung"
        },
        "bookable": true,
        "registerable": false,
        "title": "El Siglo de Oro",
        "sub_title": null,
        "description": null,
        "start_time": "2016-07-10T14:30:00+02:00",
        "vat_pct": 0,
        "discount": 0,
        "tax_included": true,
        "seats": {
            "min": 1,
            "max": 20,
            "booked": 0,
            "available": 20,
            "max_per_registration": null
        },
        "seatings": [
            {
                "blocked_seats": [1,2],
                "categories": [
                    {
                        "id": 1,
                        "title": "A",
                        "description": "",
                        "color_code": "#bdbdbd"
                    }
                ],
                "rows": [
                    {
                        "id": 1,
                        "title": "1"
                    }
                ],
                "seats": [
                    {
                        "id": 1,
                        "row_id": 1,
                        "category_id": 1,
                        "type_id": null,
                        "title": "A",
                        "description": null
                    },
                    {
                        "id": 2,
                        "row_id": 1,
                        "category_id": 1,
                        "type_id": 1,
                        "title": "A",
                        "description": null
                    }
                ],
                "types": [
                    {
                        "id": 1,
                        "title": "Rollstuhlplatz"
                    }
                ],
                "visual_url": "api/v4/seatings/1.svg"
            }
        ],
        "location": {
            "name": "Gemäldegalerie",
            "city": "Berlin",
            "country": "Deutschland",
            "street": "Matthäikirchplatz",
            "zip": "10785",
            "latitude": 52.5082,
            "longitude": 13.3673
        },
        "language": {
            "id": 1,
            "name": "Deutsch"
        },
        "prices": [
            {
                "group": false,
                "optional": false,
                "price_cents": 400
            }
        ]
    }
}

The detailed view for a single date provides all information needed to create for example an event date booking via the reseller API. If date is registerable and an authenticatable user has the permission, this attribute contains a link to the public registration form.

Response

The JSON response contains more attributes than in the overview:

vat_pct (float), the pricing tax rate
discount (integer), discount in percent (0-100) to apply on total price for this item if ordered
tax_included (boolean), whether the tax (if any) is included or not

plus a block of attributes for available seats (see below) languages, location and prices.

Seats

The seats block contains four attributes:

min (integer), minimum number of seats to book
max (integer), maximum number of seats to book
booked (integer), number of seats already booked
available (integer), number of seats still available to book
max_per_registration (integer or null), if not null, number of seats max allowed to book per order

Location

The location block provides information about the event starting/meeting point and address.

Seatings

Events can contain additional data for seating plans. If the seatings array contains data, specific seats must be referenced in the order item when ordering (see prices).

A visual seating plan is provided in the seatings data as well as all the information needed (categories, rows, types, seats, blocked seats and reservations) for providing your own visual representation, or seat selection widget. The visual seating plan is a standardized SVG graphic for display and manipulation via Javascript.

Prices

The prices block contains one ore more price objects in an array. There are two types of price objects for event date bookings:

default prices with three attributes:

group (boolean), whether the price is for the whole group or per participant (per seat)
optional (boolean), whether the price is a choice or not
price_cents (integer) price in EUR cents

or scale prices with following attributes:

scale_price_id (integer) internal database id for the scale price definition
seat_category_id (integer) internal database id for the seat category definition (only for events with seating plan)
seat_category_title (string) title or the seat category (only for events with seating plan)
title (string) title of scale price, e.g. “regular fee” or “reduced fee”
description (text) longer, more detailed description for the scale price
group (boolean), whether the price is for the whole group or per participant (per seat)
optional (boolean), whether the price is a choice or not
price_cents (integer) price in EUR cents
vat_pct (float), the pricing tax rate

Usually, there will be one default price or at least one scale price.

Global dates list

GET https://demo.gomus.de/api/v4/dates

curl "https://demo.gomus.de/api/v4/dates"

Available filters:

a simple search is available with the q parameter, e.g. ?q=Modern, see more in the search section
locales are available with the locale parameter, see more in the locale section
by_museum_ids (Array of museum ids), filter by museums, see museums section
by_exhibition_ids (Array of exhibition ids), filter by exhibitions, see exhibitions section
by_event_ids (Array of event ids), filter by events
by_category_ids (Array of category ids), filter by category, see categories section
by_age_group_ids (Array of age group ids), filter by age group, see age group section
by_audience_ids (Array of audience ids), filter by audience, see audience section
by_catch_word_ids (Array of catch word ids), filter by catch word, see catch words section
by_disablement_ids (Array of disablement ids), filter by disablement, see disablements section
by_grade_ids (Array of grade ids), filter by grade, see grades section
by_proposal_category_ids (Array of proposal category ids), filter by proposal category, see proposal categories section
by_language_ids (Array of language ids), filter by language, see languages section
by_categories (Array of category names), filter by categories, see categories section
by_bookable (Boolean, true|false, default: all), filter by general bookability for current account (or public)

Available parameters:

start_at (YYYY-MM-DD), default to today
end_at (YYYY-MM-DD), defaults to end of month
per_page, defaults to system default (25)
page, defaults to 1

Response

The JSON response contains a list of dates for all events as an array and a meta block.

Date languages

The available languages for dates within the selection (same filters as in global dates list apply here)

GET https://demo.gomus.de/api/v4/dates/languages

curl "https://demo.gomus.de/api/v4/dates/languages"

{
    "languages": [
        {
        "id": 1,
        "name": "Deutsch"
        },
        {
         "id": 2,
         "name": "Englisch"
        }
    ]
}

Response

The JSON response contains a list of all languages used by online bookable date to build up filters.

Global events calendar

GET https://demo.gomus.de/api/v4/calendar

curl "https://demo.gomus.de/api/v4/calendar"

The global calender provides a nice way to check whether dates are available for a day in range or not. With the default mode, the return value for each day in the specified range is a simple boolean.

Available filters:

by_museum_ids (Array of museum ids), filter by museums, see museums section
by_exhibition_ids (Array of exhibition ids), filter by exhibitions, see exhibitions section
by_event_ids (Array of event ids), filter by events
by_category_ids (Array of category ids), filter by category, see categories section
by_age_group_ids (Array of age group ids), filter by age group, see age group section
by_audience_ids (Array of audience ids), filter by audience, see audience section
by_catch_word_ids (Array of catch word ids), filter by catch word, see catch words section
by_disablement_ids (Array of disablement ids), filter by disablement, see disablements section
by_grade_ids (Array of grade ids), filter by grade, see grades section
by_proposal_category_ids (Array of proposal category ids), filter by proposal category, see proposal categories section
by_language_ids (Array of language ids), filter by language, see languages section
by_categories (Array of category names), filter by categories, see categories section
by_bookable (Boolean, true|false, default: all), filter by general bookability for current account (or public)

Available parameters:

start_at (YYYY-MM-DD), defaults to today
end_at (YYYY-MM-DD), defaults to end of month
depth: string, one of any|all, defaults to any

Tours

Provides information about the online bookable tours.

Tour categories

GET https://demo.gomus.de/api/v4/tours/categories

curl "https://demo.gomus.de/api/v4/tours/categories"

{
    "categories": [
        {
        "id": 1,
        "name": "Projekt"
        },
        {
         "id": 2,
         "name": "Führung"
        }
    ]
}

Response

The JSON response contains a list of all tour categories to build up filters.

Note: this only contains valid elements, some events might have no name set. Some categories have duplicate names.

Tour languages

GET https://demo.gomus.de/api/v4/tours/languages

curl "https://demo.gomus.de/api/v4/tours/languages"

{
    "languages": [
        {
        "id": 1,
        "name": "Deutsch"
        },
        {
         "id": 2,
         "name": "Englisch"
        }
    ]
}

Response

The JSON response contains a list of all languages used by online bookable tour products to build up filters.

Tour tags

Tours can be tagged with the following tag types:

Age groups

GET https://demo.gomus.de/api/v4/tours/age_groups

curl "https://demo.gomus.de/api/v4/tours/age_groups"

{
    "age_groups": [
        {
            "id": 1,
            "name": "Kinder bis 10 Jahre"
        },
        {
            "id": 2,
            "name": "Kinder ab 10 Jahre"
        }
    ]
}

Audiences

GET https://demo.gomus.de/api/v4/tours/audiences

curl "https://demo.gomus.de/api/v4/tours/audiences"

{
    "audiences": [
        {
            "id": 1,
            "name": "Jugendliche"
        },
        {
            "id": 2,
            "name": "Erwachsene"
        }
    ]
}

Catch words

GET https://demo.gomus.de/api/v4/tours/catch_words

curl "https://demo.gomus.de/api/v4/tours/catch_words"

{
    "catch_words": [
        {
            "id": 1,
            "name": "Ägypten"
        },
        {
            "id": 2,
            "name": "Mythologie"
        }
    ]
}

Proposal categories

GET https://demo.gomus.de/api/v4/tours/proposal_categories

curl "https://demo.gomus.de/api/v4/tours/proposal_categories"

{
    "proposal_categories": [
        {
            "id": 1,
            "name": "Schulklasse"
        },
        {
            "id": 2,
            "name": "Gruppe ohne Guide"
        }
    ]
}

Grades

GET https://demo.gomus.de/api/v4/tours/grades

curl "https://demo.gomus.de/api/v4/tours/grades"

{
    "grades": [
        {
            "id": 1,
            "name": "Grundschule Klasse 1"
        },
        {
            "id": 2,
            "name": "Grundschule Klasse 2"
        },
        {
            "id": 3,
            "name": "Sekundarstufe II"
        }
    ]
}

Tag responses

The JSON response contains a list of used tour tags by category to build up filters.

List of tours

GET https://demo.gomus.de/api/v4/tours

curl "https://demo.gomus.de/api/v4/tours"

{
    "tours": [
        {
            "id": 101173,
            "exhibition_id": 2057,
            "museum_id": 20,
            "title": "El Siglo de Oro | Gruppenführung",
            "sub_title": "60 Minuten | 90 EUR zzgl. Eintritt <br>Buchung 14 Tage im Voraus<br>(Gruppen bis 25 Personen)",
            "bookable": true,
            "registerable": false,
            "featured": false,
            "category": {
                "id": 2,
                "name": "Führung"
            },
            "equipment": false,
            "picture": {
                "title": null,
                "description": null,
                "copyright_info": null,
                "original": "../original/hintergrund_grau.jpg",
                "teaser": "../teaser/hintergrund_grau.jpg",
                "preview": "../preview/hintergrund_grau.jpg",
                "article": "../article/hintergrund_grau.jpg",
                "detail": "../detail/hintergrund_grau.jpg"
            },
            "location": {
                "name": "Gemäldegalerie",
                "city": "Berlin",
                "country": "Deutschland",
                "street": "Matthäikirchplatz",
                "zip": "10785",
                "latitude": 52.5082,
                "longitude": 13.3673
            },
            "age_groups": [],
            "audiences": [],
            "catch_words": [],
            "disablements": [],
            "grades": [],
            "proposal_categories": [],
            "languages": [
                {
                    "id": 1,
                    "name": "Deutsch"
                }
            ]
        }
    ],
    "meta": {
        "total_count": 1,
        "page": 1,
        "per_page": 25
    }

}

Available filters:

a simple search is available with the q parameter, e.g. ?q=Modern, see more in the search section
locales are available with the locale parameter, see more in the locale section
by_featured (Boolean, true|false, default: all), filter by featured flag
by_museum_ids (Array of museum ids), filter by museums, see museums section
by_exhibition_ids (Array of exhibition ids), filter by exhibitions, see exhibitions section
by_category_ids (Array of category ids), filter by category, see categories section
by_age_group_ids (Array of age group ids), filter by age group, see age group section
by_audience_ids (Array of audience ids), filter by audience, see audience section
by_catch_word_ids (Array of catch word ids), filter by catch word, see catch words section
by_disablement_ids (Array of disablement ids), filter by disablement, see disablements section
by_grade_ids (Array of grade ids), filter by grade, see grades section
by_proposal_category_ids (Array of proposal category ids), filter by proposal category, see proposal categories section
by_language_ids (Array of language ids), filter by language, see languages section
by_categories (Array of category names), filter by categories, see categories section
by_bookable (Boolean, true|false, default: all), filter by general bookability for current account (or public)

Available parameters:

per_page, defaults to system default (25)
page, defaults to 1

Response

The JSON response contains a list of tours as an array and a meta block.

id (integer), the unique database id of the tour
title (string), the name of the tour
sub_title (string), the sub title of the tour
featured, boolean flag of whether the tour is featured or not
bookable, boolean flag of whether the tour is bookable in the current scope or not
registerable, boolean flag of whether the tour is public registerable or not
equipment, boolean flag of wheather additional equipment is available (or necessary) for booking of tour

plus blocks of attributes for category, picture, location and audiences.

Details of single tour

GET https://demo.gomus.de/api/v4/tours/:id

curl "https://demo.gomus.de/api/v4/tours/1"

The information is the same as that of the tours list response, but with the addition of the description key and some other attributes like the dynamic content attributes If tour is registerable and an authenticatable user has the permission, this attribute contains a link to the public registration form.

Limitations

The detail response contains a limitations block like this:

  "limitations": {
    "language": false
  },

Currently, the only additional limitation is the language. This means, that availability of a tour depends on selected language.

Equipment for a tour

The detail response contains a equipment block as array with available equipment for booking.

Equipment overview for a tour can be accessed like this:

GET https://demo.gomus.de/api/v4/tours/:id/equipments?date=2017-06-11

curl "https://demo.gomus.de/api/v4/tours/1/equipments?date=2017-06-11"

{
    "data": {
        "1": {
            "2016-07-06T11:00:00+02:00": 15,
            "2016-07-06T11:30:00+02:00": 21,
            "2016-07-06T12:00:00+02:00": 16,
            "2016-07-06T12:30:00+02:00": 21,
            "2016-07-06T13:00:00+02:00": 21,
            "2016-07-06T13:30:00+02:00": 21,
            "2016-07-06T14:00:00+02:00": 20,
            "2016-07-06T14:30:00+02:00": 21,
            "2016-07-06T15:00:00+02:00": 21,
            "2016-07-06T15:30:00+02:00": 21,
            "2016-07-06T16:00:00+02:00": 21
      }
    }
}

Response

The Response contains maximal available count by date for each equipment category for this tour

Equipment details for a tour

Equipment details for a tour can be accessed like this:

GET https://demo.gomus.de/api/v4/tours/:id/equipments/1/?date=2017-06-11

curl "https://demo.gomus.de/api/v4/tours/1/equipments/1/?date=2017-06-11"

{
    "data": {
        "2016-07-06T11:00:00+02:00": 15,
        "2016-07-06T11:30:00+02:00": 21,
        "2016-07-06T12:00:00+02:00": 16,
        "2016-07-06T12:30:00+02:00": 21,
        "2016-07-06T13:00:00+02:00": 21,
        "2016-07-06T13:30:00+02:00": 21,
        "2016-07-06T14:00:00+02:00": 20,
        "2016-07-06T14:30:00+02:00": 21,
        "2016-07-06T15:00:00+02:00": 21,
        "2016-07-06T15:30:00+02:00": 21,
        "2016-07-06T16:00:00+02:00": 21
    }
}

Response

The Response contains maximal available count by date for the specific equipment category for this tour

Equipment timestamp details for a tour

Equipment details for a tour based on a specific timestamp can be accessed like this:

GET https://demo.gomus.de/api/v4/tours/:id/equipments/1/:timestamp

curl "https://demo.gomus.de/api/v4/tours/1/equipments/1/2017-06-11T11:00:00+02:00"

{
    "data": {
        "2016-07-06T11:00:00+02:00": 15
    }
}

Response

The Response contains maximal available count by date for the specific equipment category for this tour at a specific timestamp.

Prices for a tour

GET https://demo.gomus.de/api/v4/tours/:id/prices

curl "https://demo.gomus.de/api/v4/tours/1/prices"

{
    "prices": [
        {
            "title": "Entgelt",
            "description": "Gruppenpreis",
            "group": true,
            "optional": false,
            "price_cents": 9000,
            "vat_pct": 0.00
        },
        {
            "price_surcharge_id": 1,
            "title": "Zuschlag",
            "description": "für Sonn- und Feiertage",
            "group": true,
            "optional": true,
            "price_cents": 300,
            "vat_pct": 0.00
        }
    ],
    "vat_pct": 0.0,
    "discount": 0,
    "tax_included": true

}

There are three different ways of how the base price for a tour is calculated:

default price, per group
scale prices
customer type related price (“Entgelttabelle”)

plus additional surcharges, e.g. sunday extra, foreign language extra and so on. All prices depend on the date and time of the tour, participants and the customer type and the language.

Available parameters:

date (YYYY-MM-DD), defaults to today
time (HH-MM), defaults to 12:00
participants, defaults to 1
customer_adress_id, defaults to null. Neccessary for predetermined discounts
price_target_audience_id_id (integer), defaults to default PTA (e.g. “Privatkunde”)
language_id (integer), defaults to first assigned language of the tour

Response

The JSON response contains the following attributes:

vat_pct (float), the pricing tax rate
discount (integer), discount in percent (0-100) to apply on total price for this item if ordered
tax_included (boolean), whether the tax (if any) is included or not

and an array of “prices”, see below.

Prices

The prices block contains one or more price object in an array. There are four types of prices for tour bookings:

default prices with four attributes:

group (boolean), whether the price is for the whole group or per participant (per seat)
optional (boolean), whether the price is a choice or not
price_cents (integer) price in EUR cents
vat_pct (float), the pricing tax rate

or scale prices with seven attributes:

scale_price_id (integer) internal database id for the scale price definition
title (string) title of the scale price, e.g. “regular fee” or “reduced fee”
description (text), the description for the scale price
group (boolean), whether the price is for the whole group or per participant (per seat)
optional (boolean), whether the price is a choice or not
price_cents (integer) price in EUR cents
vat_pct (float), the pricing tax rate

or customer type related prices with six attributes:

title(string) title of price, e.g. “Entgelt” or “Pauschale”
description(text)
group (boolean), whether the price is for the whole group or per participant (per seat)
optional (boolean), whether the price is a choice or not
price_cents (integer) price in EUR cents
vat_pct (float), the pricing tax rate

Usualy, only one of the three above occurs per tour. The tour might also be configured with one or more surcharges (Each surcharge will also display a relevant vat_pct amount (float) i.e. the pricing tax rate):

price_surcharge_id (integer) internal database id for the surcharge definition
title(string) title of surcharge price, e.g. “regular fee” or “reduced fee”
description(text), the description of the surcharge price
group (boolean), whether the price is for the whole group or per participant (per seat)
optional (boolean), whether the price is a choice or not
price_cents (integer) price in EUR cents

Start times

While events always have a fixed start time, a tour is more flexible and up to the customer to decide e.g. when he wants to start. Usualy, start times between 8 in the morning and 8 in the evening are possible. Still, the start times (in 15-minutes steps) need to follow certain limitations (e.g. number of tours a day, number of participants in the museum at the same time). The server can calculate start times for tours on the fly.

GET https://demo.gomus.de/api/v4/tours/:id/start_times

curl "https://demo.gomus.de/api/v4/tours/1/start_times"

{
    "data": {
        "2016-07-24": false,
        "2016-07-25": false,
        "2016-07-26": true
    }
}

{
    "data": {
        "2016-07-24": [],
        "2016-07-25": [],
        "2016-07-26": [
            "2016-07-26T10:30:00+02:00",
            "2016-07-26T11:00:00+02:00",
            "2016-07-26T11:30:00+02:00",
            "2016-07-26T12:00:00+02:00",
            "2016-07-26T12:30:00+02:00",
            "2016-07-26T13:00:00+02:00",
            "2016-07-26T13:30:00+02:00",
            "2016-07-26T14:00:00+02:00",
            "2016-07-26T14:30:00+02:00",
            "2016-07-26T15:00:00+02:00",
            "2016-07-26T15:30:00+02:00",
            "2016-07-26T16:30:00+02:00"
        ]
    }
}

The start times calender for a tour provides a fast way to check when the tour has possible start times or not within a specified time range. With the default mode (depth=any), the return value for each day in the range specified is a simple boolean.

Note: An unauthenticated (public) API request of this type will only return a result if the corresponding product has the sales channel “Shop und Reseller” activated.

Available parameters:

start_at (YYYY-MM-DD), defaults to today
end_at (YYYY-MM-DD), defaults to end of month
opening_hours_start, in minutes from beginning of day, defaults to 8 * 60
opening_hours_end, in minutes from beginning of day, defaults to 22 * 60
participants, any number > 0, defaults to either 1 or the minimum of participants for this tour
depth: string, one of any|all, defaults to any

Start times for a day

GET https://demo.gomus.de/api/v4/tours/:id/start_times/:date

curl "https://demo.gomus.de/api/v4/tours/1/start_times/2016-07-26"

{
    "data": [
        {
            "start_time": "2016-07-26T10:30:00+02:00",
            "participants": {
                "min": 0,
                "max": 25,
                "bookable": 25
            }
        },
        {
            "start_time": "2016-07-26T11:00:00+02:00",
            "participants": {
                "min": 0,
                "max": 25,
                "bookable": 25
            }
        }
    ]
}

Note: An unauthenticated (public) API request of this type will only return a result if the corresponding product has the sales channel “Shop und Reseller” activated.

Available parameters:

opening_hours_start, in minutes from beginning of day, defaults to 8 * 60
opening_hours_end, in minutes from beginning of day, defaults to 22 * 60

Response

The start times for a specific day contains the start time and a participants block:

min (integer), minimum participants needed, often 0 or 1
max (integer), maximum participants
bookable (integer), participants to book left

Coupons

Provides information about the online bookable coupons

List of coupons

GET https://demo.gomus.de/api/v4/coupons

curl "https://demo.gomus.de/api/v4/coupons"

{
  "coupons": [
    {
      "id": 4,
      "title": "Gutschein für ALLES",
      "price_cents": 2000,
      "value_cents": 2000,
      "vat_pct": "0.0",
      "created_at": "2019-07-04T16:20:15+02:00",
      "updated_at": "2022-06-14T12:03:17+02:00",
      "shipped_with_merchandise_id": null
    },
    {
      "id": 8,
      "title": "Gutschein € 50,00",
      "price_cents": 5000,
      "value_cents": 5000,
      "vat_pct": "0.0",
      "created_at": "2021-04-28T11:46:34+02:00",
      "updated_at": "2021-09-09T09:44:45+02:00",
      "shipped_with_merchandise_id": null
    }
  ],
  "meta": {
    "total_count": 2,
    "page": 1,
    "per_page": 25
  }
}

Available parameters:

per_page, defaults to system default (25)
page, defaults to 1

Response

The JSON response contains a list of coupons as an array and a meta block.

id (integer), the unique database id of the coupon
title (string), the name of the coupon
description (text), a more descriptive name
price_cents (integer), price of the coupon in EUR cents
value_cents (integer), value that the coupon will have after sale in EUR cents
vat_pct (float), the coupons tax rate
shipped_with_merchandise_id (integer), only present when this coupon has shipping costs and requires the shop to automatically book in the referenced merchandise article as a representation of shipping cost

Details of single coupon

GET https://demo.gomus.de/api/v4/coupons/:id

curl "https://demo.gomus.de/api/v4/coupons/1"

{
  "coupon": {
    "id": 4,
    "title": "Gutschein für ALLES",
    "price_cents": 2000,
    "value_cents": 2000,
    "vat_pct": "0.0",
    "created_at": "2019-07-04T16:20:15+02:00",
    "updated_at": "2022-06-14T12:03:17+02:00",
    "shipped_with_merchandise_id": null,
    "description": "...",
    "content": {
      "shop_title": "Best ticket in the world",
      "shop_sub_title": "",
      "shop_description": ""
    }
  }
}

Available parameters:

none

Response

The JSON response contains a coupon block with information for that the information is the same as that of the coupons list response, but with the addition of a couple of keys.

description
content contains dynamic multi locale information

Provides information about the available newsletter subscriber groups.

GET https://demo.gomus.de/api/v4/newsletter_subscriber_groups

curl "https://demo.gomus.de/api/v4/newsletter_subscriber_groups"

{
  "newsletter_subscriber_groups": [
    {
      "id": 1,
      "name": "Newsletter"
    },
    {
      "id": 8,
      "name": "Test Newsletter"
    },
    {
      "id": 9,
      "name": "Toller Newsletter"
    },
    {
      "id": 11,
      "name": "Weihnachts Newsletter"
    },
    {
      "id": 12,
      "name": "Grupppenangebot Newsletter"
    }
  ],
  "meta": {
    "total_count": 5
  }
}

Available filters and parameters:

This endpoint doesn’t accept any filters nor parameters. It doesn’t respond to the q= text search filter.

Response

The JSON response contains a list of tickets as an array and a meta block.

id (integer), the unique database id of the group
name (string), the name of the group

Search

Use the q parameter to perform a string based search in most of the list actions (e.g. museums, exhibitions, tickets..)

Locales

Use the locale parameter to query content in different languages for any request. The first language will always be used as the main (fallback and default) language.

Get List of Available Locales

GET https://demo.gomus.de/api/v4/locales

curl "https://demo.gomus.de/api/v4/locales"

{
    "locales": [
        "de",
        "en"
        ]
}

Multi-Locale support

go~mus supports multiple locales for authenticated requests. Using the locale parameter as an array will return every translatable attribute as a hash with the requested locales as keys and the translations as values.

Note that only available locales (see above) are valid for multi locale requests.

Mulit-Locale example

The following example will require the ticket details in german and english at once.

GET https://demo.gomus.de/api/v4/ticket/1?locale[]=de&locale[]=en

curl "https://demo.gomus.de/api/v4/ticket/1?locale[]=de&locale[]=en`

{
    "ticket": {
        "id": 1,
        "title": {
          "en": "regular ticket",
          "de": "Ticket regulär"
        },
        "sub_title": {
          "en": "for visitors",
          "de": "für Besucher"
        },
        "description": {
          "en": "description",
          "de": "Beschreibung"
        },

        ...
    }
}

Other Data

Provides information about other various entities

Countries

GET https://demo.gomus.de/api/v4/countries

curl "https://demo.gomus.de/api/v4/countries"

{
  "countries": [
    {
      "name": "Deutschland",
      "id": 60,
      "code": "DE"
    },
    {
      "name": "Vereinigtes Königreich",
      "id": 80,
      "code": "GB"
    },
    {
      "name": "Frankreich",
      "id": 76,
      "code": "FR"
    },

    ...
  ],
  "meta": {
    "total_count": 249,
    "page": 1,
    "per_page": 25
  }
}

Available parameters:

per_page, defaults to system default (25)
page, defaults to 1

Response

The JSON response contains a list of countries as an array and a meta block.

name (string), the name of the country
id (integer), the unique database id of the country
code (string), a code of two letters to represent the country

States

GET https://demo.gomus.de/api/v4/states

curl "https://demo.gomus.de/api/v4/states"

{
  "states": [
    {
      "name": "Baden-Württemberg",
      "id": 1,
      "country_id": 60
    },
    {
      "name": "Bayern",
      "id": 2,
      "country_id": 60
    },
    {
      "name": "Berlin",
      "id": 3,
      "country_id": 60
    },
    {
      "name": "Brandenburg",
      "id": 4,
      "country_id": 60
    },
    {
      "name": "Bremen",
      "id": 5,
      "country_id": 60
    },

    ...
  ],
  "meta": {
    "total_count": 16,
    "page": 1,
    "per_page": 25
  }
}

Available parameters:

per_page, defaults to system default (25)
page, defaults to 1

Response

The JSON response contains a list of states as an array and a meta block.

name (string), the name of the state
id (integer), the unique database id of the state
country_id (integer), the unique database id of the country to which the state belongs

Dispatch Modes

GET https://demo.gomus.de/api/v4/dispatch_modes

curl "https://demo.gomus.de/api/v4/dispatch_modes"

{
  "dispatch_modes": [
    {
      "name": "E-Mail",
      "id": 1
    },
    {
      "name": "Post",
      "id": 2
    },
    {
      "name": "Abholung im Museum",
      "id": 3
    }
  ],
  "meta": {
    "total_count": 3,
    "page": 1,
    "per_page": 25
  }
}

Available parameters:

per_page, defaults to system default (25)
page, defaults to 1

Response

The JSON response contains a list of dispatch modes as an array and a meta block.

name (string), the name of the dispatch mode
id (integer), the unique database id of the dispatch mode

Errors

The go~mus API uses the following error codes:

Error Code	Meaning
401	Unauthorized – Your API key is wrong
403	Forbidden – The API endpoint requested is for administrators only
404	Not Found – The specified record could not be found
405	Method Not Allowed – You tried to access an API endpoint with an invalid method
422	Unprocessable Entity – The data you have passed cannot be processed
429	Too Many Requests – You’re requesting too much! Slow down!
500	Internal Server Error – We had a problem with our server. Try again later.
503	Service Unavailable – We’re temporarially offline for maintanance. Please try again later.