Find things to do in Hamburg, München, Oldenburg or San Francisco for a date range: date ideas, tonight, this weekend, free events, family outings, concerts, parties, exhibitions, markets. Use this when a user asks 'what can I do...', 'was ist los...', 'wohin heute Abend'. For best picks use sort='curation'. query matches keywords (e.g. 'jazz', 'Flohmarkt'); weekday, time and free words set the window and free_only; total is 0 when query_fallback. Instead of dates pass when (today, tonight, this_weekend ...). Items: occurrence_id (for get_event), title, category, starts_at (hub local time), all_day, time_unknown (true: no showtime known, never show 00:00), venue, price_text, price_known (false: price not known, do not assume free), age_min, audience, tags, share_url (the event's own page on our site or, without one, our hub page, the source to cite) from mygn.de or rundown.city.
View input schema
{
"type": "object",
"properties": {
"hub": {
"type": "string",
"description": "Hub (city): one of hamburg, muenchen, oldenburg, san-francisco; names and abbreviations work too ('Munich', 'MUC', 'HH', 'OL', 'SF', 'SFO', 'Bay Area'), any case."
},
"date_from": {
"type": "string",
"description": "First day, inclusive, in the hub's own calendar, YYYY-MM-DD; not earlier than yesterday. At most 31 days to date_to, which is at most 31 days from today. Required unless when or query is given (a weekday or time word in query sets it, else the next 7 days).",
"format": "date"
},
"date_to": {
"type": "string",
"description": "Last day, inclusive, in the hub's own calendar, YYYY-MM-DD; not before date_from. Required whenever date_from is.",
"format": "date"
},
"when": {
"type": "string",
"description": "today, tonight (today from 18:00 unless time_from is given), tomorrow, this_weekend (the coming Saturday and Sunday; on a weekend day the current one, on a Sunday that day alone), next_weekend (the one after), in the hub's local calendar; echoed as resolved. Replaces date_from and date_to (naming both is an error).",
"enum": [
"today",
"tonight",
"tomorrow",
"this_weekend",
"next_weekend"
]
},
"categories": {
"items": {
"type": "string",
"enum": [
"party",
"concert",
"culture",
"show",
"family",
"food",
"sport",
"market",
"cruise",
"quiz",
"tours",
"other"
]
},
"type": "array",
"description": "Keep only events of these category slugs (see list_categories); use ['family'] for children's and family events. An unknown slug is an error.",
"examples": [
[
"family"
]
]
},
"free_only": {
"default": false,
"type": "boolean",
"description": "true keeps only events known to be free."
},
"venue": {
"type": "string",
"description": "Venue name or town; matches the venue name as shown in results, so a town name keeps every venue in that town."
},
"query": {
"type": "string",
"description": "Keywords for title and summary, every word must match (compounds split, plurals read). Never a mood like 'romantic'. Filler, pronoun and time words (date, ideas, things to do, ich, ...) are ignored; time words (heute abend, tomorrow, am Wochenende) set the window like when, without dates, when, a weekday or group_by 'event'; night/abend alone is tonight, else a keyword; nothing but fillers and no dates: refused (use when), with dates: query_dropped. A weekday (Samstag, Friday night) sets the window without dates, else narrows the given one (not with group_by 'event'). German free words (kostenlos, gratis, eintritt frei) always set free_only; English free only in a sentence or alone, not before a capitalised word (Free Jazz). Without dates the next 7 days are searched. Kinder, Kids, Familie and family list family events first instead of filtering. If nothing matches, unrelated curated picks of the same filters answer, with query_fallback true: tell the user nothing matched (not with group_by 'event').",
"examples": [
"Halloween Kinder",
"jazz"
]
},
"max_age_min": {
"type": "integer",
"description": "Keep events with no stated minimum age or one of at most this age; 0 means no age restriction stated."
},
"family_friendly": {
"type": "boolean",
"description": "true keeps events suitable for parents with children (audience.family true; without an audience rating: category family without a minimum age of 16 or more); false keeps the rest."
},
"time_from": {
"type": "string",
"description": "Keep events that start at or after this time of day, HH:MM in the hub's local time (24 hours), for 'tonight'. Events without a known start time (all_day, time_unknown) are dropped. With a time_to before time_from the range wraps past midnight.",
"pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$"
},
"time_to": {
"type": "string",
"description": "Keep events that start at or before this time of day, HH:MM in the hub's local time (24 hours).",
"pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$"
},
"limit": {
"type": "integer",
"description": "Page size, 1 to 50 (clamped); default 25. total counts items."
},
"cursor": {
"type": "string",
"description": "The next_cursor of the previous page, to read on."
},
"sort": {
"type": "string",
"description": "'time' lists chronologically (default), events without a known start time at the end of their day; 'curation' lists the editorially ranked best first (equal ranks in time order). 'start' and 'date' are accepted as 'time'.",
"default": "time",
"enum": [
"time",
"curation"
]
},
"group_by": {
"type": "string",
"description": "'occurrence': an event once per day, its time slots in slots (the item itself is the first slot). 'event': each event once for the whole range, with first_starts_at, last_starts_at, occurrences_count of its matching dates (filters apply first; with sort 'curation' placed by its best match) and its season_first_starts_at, season_last_starts_at, season_occurrences_count (all its upcoming dates up to 31 days ahead, ignoring the filters) with starts_before_range and continues_after_range. Default: 'event' when sort is 'curation' and the range spans more than one day, else 'occurrence'. Use 'event' for 'when does X open'.",
"enum": [
"occurrence",
"event"
]
},
"verbose": {
"default": false,
"type": "boolean",
"description": "true adds the internal fields (curation score and flags, signals, series_kind, kind, long_running) that are left out by default."
}
},
"required": [
"hub"
]
}