Skip to content
Uranus Docs
Esc
↑↓navigate↵open⌘Jpreview

1. Get events

Returns events matching the supplied filters.

GET query parameters are validated by the API. Unknown query parameters result in a bad-request response. Array-valued filters are supplied as comma-separated values.

Pagination – The API supports two pagination strategies.

Offset pagination:
Use offset together with limit for ad hoc requests where a specific result page is needed.

Cursor pagination:
Use last_event_start_at together with last_event_date_uuid for stable, continuous pagination through the event list.

Cursor pagination is best suited for endless presentation of events, such as event lists on websites.
This is the pagination strategy used by kulturbytes websites.
Both last_event_start_at and last_event_date_uuid must be provided together.

Response properties

The response contains an array of events and pagination information.

Required event properties

Each event object includes the following properties:

  • search_rank — Search relevance rank.
  • uuid — Unique identifier of the event.
  • date_uuid — Unique identifier of the event date.
  • date_slug — Slug identifying the event date.
  • title — Event title.
  • start_date — Start date in YYYY-MM-DD format.
  • start_time, — Start time in HH-MM format.
  • org_uuid — Unique identifier of the organizing organization.
  • org_name — Name of the organizing organization.

These properties are included in each event object, even when their values are null or their arrays are empty.

Optional event properties

Other properties may be omitted from an event object when no value is available. These include, for example:

  • summary
  • end_date, end_time, entry_time, duration, all_day
  • org_postal_code, org_city, org_country
  • space_uuid, space_name, space_accessibility_flags
  • venue_uuid, venue_name, venue_city, venue_street, venue_house_number, venue_postal_code, venue_state, venue_country, venue_lat, venue_lon
  • image_uuid, image_path, image_ai_label
  • categories, event_types, languages, tags
  • price_type, min_price, max_price, currency
  • ticket_link
  • min_age, max_age
  • visitor_info_flags, release_status

Pagination properties

The data object contains the following pagination properties:

  • events — Array of matching events. An empty result is returned as an empty array.
  • last_event_date_uuid — Date UUID of the last returned event; may be null when no events are returned.
  • last_event_start_at — Start timestamp of the last returned event; may be null when no events are returned.

For cursor pagination, pass both last_event_start_at and last_event_date_uuid from the previous response to retrieve the next page.

GET/api/events
Query parameters
offsetinteger<int64>

Offset of the first result.

Use together with limit for offset-based pagination.

min 0
limitinteger<int64>

Maximum number of results requested.

min 1
last_event_start_atstring

Start timestamp of the last event date returned by the previous request.

Omit this parameter for the first request.

For subsequent requests, use together with last_event_date_uuid to continue cursor pagination.

Both parameters must be provided together.

last_event_date_uuidstring<uuid>

UUID of the last event date returned by the previous request.

Omit this parameter for the first request.

For subsequent requests, use together with last_event_start_at to continue cursor pagination.

Both parameters must be provided together.

langstring

Two-letter language code used for localized data.

Supported language codes include de (German), da (Danish), and en (English).

All localized labels in the response are returned in the selected language, including event types, genres, accessibility features, visitor information, and other translated values.

startstring

Start date in YYYY-MM-DD format. Defaults to the current date when omitted.

matches ^\d{4}-\d{2}-\d{2}$
endstring

Inclusive end date in YYYY-MM-DD format.

matches ^\d{4}-\d{2}-\d{2}$
timestring

Event-time filter. The value must contain a start time and an end time, separated by a comma.

Supported time formats:

  • HH,HH for hours in 24-hour format.
  • HHMM,HHMM for hours and minutes in 24-hour format.

Examples:

  • 10,14 matches events from 10:00 to 14:00.
  • 1030,1545 matches events from 10:30 to 15:45.

The start time must be before the end time.

categoriesstring

Comma-separated list of one or more category IDs.

Available categories:

  • 1 — Culture
  • 2 — Education
  • 3 — Sports
  • 4 — Leisure
  • 5 — Family
  • 6 — Society

Multiple categories can be combined using commas.

searchstring

Full-text search query.

venuestring

Venue name search filter.

The value can contain one or more names, separated by commas. Each name may optionally start or end with * as a wildcard. A wildcard matches any number of characters.

Examples:

  • theater — exact name match
  • theater,museum — matches either name
  • *theater — name ending with "theater"
  • theater* — name starting with "theater"
  • *theater* — name containing "theater"
  • *theater,*museum* — names ending with "theater" or containing "museum"
space_typesstring

One or more space types, separated by commas.

Known space types can be fetched from /api/choosable-space-types.

Examples:

  • club — a single space type
  • multifunctional_room,cafe — multiple space types
countriesstring

One or more country codes, separated by commas.

Country codes use the three-letter ISO 3166-1 alpha-3 format.

Examples:

  • DEU — Germany
  • DNK,NOR — Denmark and Norway
postal_codestring

Comma-separated list of postal code patterns.

Use * as a wildcard for partial matching:

  • 249* matches postal codes starting with 249.
  • *509 matches postal codes ending with 509.
  • *608* matches postal codes containing 608.
  • 249*,2348*,*6000* matches any of the specified patterns.

Without *, an exact match is performed.

titlestring

Searches the event title for the specified text.

* can be used at the beginning or end of the value as a wildcard. A wildcard matches any number of characters.

Examples:

  • theater — searches for the title "theater"
  • *theater — searches for titles ending with "theater"
  • theater* — searches for titles starting with "theater"
  • *theater* — searches for titles containing "theater"
citystring

One or more city names, separated by commas.

* can be used at the beginning or end of a city name as a wildcard. A wildcard matches any number of characters.

Examples:

  • Flensburg — searches for Flensburg
  • Flensburg,Kiel — searches for Flensburg or Kiel
  • *burg — searches for cities ending with "burg"
  • Kiel* — searches for cities starting with "Kiel"
  • *burg* — searches for cities containing "burg"
event_typesstring

One or more event type IDs, separated by commas.

Available event types can be fetched from /api/event/type-genre-lookup.

This parameter cannot be used together with genres.

genresstring

One or more genre IDs, separated by commas.

Available genres can be fetched from /api/event/type-genre-lookup.

This parameter cannot be used together with event_types.

tagsstring

Comma-separated tags.

Example: theater,musical,family

accessibilitystring

One or more accessibility feature IDs, separated by commas.

When multiple IDs are specified, the event location or space must provide all requested accessibility features.

IDs and short descriptions of available accessibility features can be fetched from /api/accessibility/flags.

Example: 1,3,5 requires all three accessibility features.

visitor_infosstring

One or more visitor-information IDs, separated by commas.

When multiple IDs are specified, the event must provide all requested visitor information.

IDs and short descriptions of available visitor information can be fetched from /api/visitor-info/flags.

Example: 1,3,5 requires all three visitor-information features.

agestring

Age filter.

One or two age values can be specified, separated by a comma.

With two values, only events are returned that can be attended by people from the lower age to the higher age.

With one value, events are returned that can be attended by people of the specified age.

Examples:

  • 6 — events that can be attended by a 6-year-old
  • 6,12 — events that can be attended by people aged 6 to 12
pricestring

Price filter. Syntax is interpreted by the API filter parser.

lonnumber<double>

Longitude of the center point for geographic filtering.

The coordinate is specified as an EPSG:4326 longitude.

The geographic filter is applied when lon, lat, and radius are provided together.

latnumber<double>

Latitude of the center point for geographic filtering.

The coordinate is specified as an EPSG:4326 latitude.

The geographic filter is applied when lon, lat, and radius are provided together.

radiusnumber<double>

Radius of the geographic filter in meters.

The geographic filter is applied when lon, lat, and radius are provided together. Events within the resulting circle are returned.

org_uuidsstring

One or more organization UUIDs, separated by commas.

Events belonging to any of the specified organizations are returned.

venue_uuidsstring

One or more venue UUIDs, separated by commas.

Events taking place at any of the specified venues are returned.

space_uuidsstring

One or more space UUIDs, separated by commas.

Events taking place in any of the specified spaces are returned.

event_uuidsstring

One or more event UUIDs, separated by commas.

Events matching any of the specified UUIDs are returned.

geolist_regionstring

Geographic region filter.

The value contains three comma-separated region slugs: country, state or region, city.

Example: deutschland,schleswig-holstein,flensburg

The specified region is used to determine the geographic area for event filtering.

This parameter cannot be combined with portal.

portalstring<uuid>

Portal UUID used to filter events belonging to a specific portal.

This parameter cannot be combined with geolist_region.

Responses
200

Events returned successfully.

400

Invalid request or filter parameter.

object
500

Internal server error.

object
Try it
Server
Parameters
Request
curl -X GET "https://api.kulturbytes.de/api/events"
Response
{
  "service": "Uranus API",
  "api_version": "1.0",
  "response_type": "get-events",
  "status": 200,
  "timestamp": "2026-09-23T05:22:50Z",
  "metadata": {
    "response_time_ms": 6
  },
  "data": {
    "events": [
      {
        "search_rank": 1,
        "uuid": "01a09fe9-0b46-7624-b0c7-4693e24250a2",
        "date_uuid": "01a0a01b-0557-762a-8f1a-7bb307e4c37a",
        "date_slug": "202609230900",
        "title": "Malkreis Glücksburg",
        "subtitle": "Deine kreative Zeit für Farbe, Ideen und gemeinsames Gestalten",
        "summary": "Im Malkreis Glücksburg kannst du eigene Bildideen verwirklichen, neue Techniken ausprobieren und dich mit anderen Kreativen austauschen.",
        "start_date": "2026-09-23",
        "start_time": "09:00",
        "end_date": "2026-09-23",
        "end_time": "12:00",
        "space_uuid": "019eb0ad-e0a5-711b-b216-6cd9fde38acf",
        "space_name": "Atelier Kreativecke",
        "venue_uuid": "019eb0a5-852e-753a-a1cb-ad5a9a5948fb",
        "venue_name": "Atelier Kreativecke",
        "venue_city": "Glücksburg",
        "venue_street": "Rathausstaße",
        "venue_house_number": "11",
        "venue_postal_code": "24960",
        "venue_state": "SH",
        "venue_country": "DEU",
        "venue_lat": 54.8349485775689,
        "venue_lon": 9.54897141524646,
        "image_uuid": "01a09fed-c812-7d7e-b5ff-312de6185160",
        "image_path": "https://api.kulturbytes.de/api/image/01a09fed-c812-7d7e-b5ff-312de6185160",
        "image_ai_label": "none",
        "org_uuid": "019ea6d1-e26e-79f3-9c4b-6f9f54e4c1d9",
        "org_name": "Atelier Kreativecke",
        "categories": [
          1,
          2,
          4,
          6
        ],
        "event_types": [
          {
            "type_id": 34,
            "genre_id": 0
          },
          {
            "type_id": 40,
            "genre_id": 0
          },
          {
            "type_id": 8,
            "genre_id": 0
          }
        ],
        "languages": [],
        "tags": [],
        "min_age": 18,
        "max_age": 111,
        "price_type": "not_specified",
        "visitor_info_flags": "136352024",
        "release_status": "released"
      }
    ],
    "last_event_date_uuid": "01a0a91d-17a4-72a5-b67a-46389cc97e27",
    "last_event_start_at": "2026-09-23T14:30:00+02:00"
  }
}