events-search

Lists every performance of a single title, ordered by date, optionally narrowed to one city and a date range. Use this when the user asks for all dates of a title, or for its dates in a given city or on a given weekend - search_events returns only the nearest performance per title. Each performance carries its own venue, date, price, free places and buy_url. Only future performances are returned unless date_from says otherwise.

{
  "type": "object",
  "properties": {
    "artist_id": {
      "type": "integer",
      "description": "Title identifier - the artist_id field from search_events results."
    },
    "city": {
      "type": "string",
      "default": null,
      "description": "City name filter (exact match, case-insensitive, diacritics required), e.g. \"Warszawa\"."
    },
    "date_from": {
      "type": "string",
      "default": null,
      "description": "Earliest performance date (YYYY-MM-DD). Defaults to today.",
      "format": "date"
    },
    "date_to": {
      "type": "string",
      "default": null,
      "description": "Latest performance date (YYYY-MM-DD), inclusive.",
      "format": "date"
    },
    "page": {
      "type": "integer",
      "default": 1,
      "description": "Page number, starting at 1.",
      "minimum": 1
    },
    "items_per_page": {
      "type": "integer",
      "default": 20,
      "description": "Performances per page. Defaults to 20.",
      "minimum": 1,
      "maximum": 100
    }
  },
  "required": [
    "artist_id"
  ]
}

Searches performances (concerts, theatre plays, festivals, stand-up shows and more) currently on sale on Biletyna.pl, a Polish ticketing platform. Every filter applies to a single performance, so city, date range and price always describe the same event. Results are deduplicated by title: each hit is the nearest matching performance of a distinct title, carrying its buy_url, venue, price and free places, plus aggregates for its city (city_events_total, city_next_event_date) and for the whole title (title_events_total, title_cities_total). Use "facets" for the distribution of matches across cities and categories. Only future performances are returned unless date_from says otherwise. Use list_performances(artist_id) for all dates of a title, get_title_details(artist_id) for its description and all cities. Full-text search is typo-tolerant. All content is in Polish. Prices are provided both in grosze (*_min_price) and PLN (*_min_price_pln); dates both as unix timestamps and human-readable *_text fields. "_meta.indexed_at" tells when the data was last refreshed - free places and prices are a snapshot from that moment.

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "default": null,
      "description": "Search phrase: event name, performer or kind of event. Typo-tolerant. Use Polish terms when possible."
    },
    "city": {
      "type": "string",
      "default": null,
      "description": "City name filter (exact match, case-insensitive, diacritics required), e.g. \"Warszawa\"."
    },
    "category": {
      "type": "string",
      "default": null,
      "description": "Event category name filter (exact match), e.g. \"koncert\", \"spektakl\", \"kabaret\"."
    },
    "date_from": {
      "type": "string",
      "default": null,
      "description": "Earliest performance date (YYYY-MM-DD). Defaults to today - past performances are never returned.",
      "format": "date"
    },
    "date_to": {
      "type": "string",
      "default": null,
      "description": "Latest performance date (YYYY-MM-DD).",
      "format": "date"
    },
    "max_price": {
      "type": "number",
      "default": null,
      "description": "Maximum price of the cheapest ticket for the performance, in PLN (not in grosze).",
      "minimum": 0
    },
    "min_rating": {
      "type": "number",
      "default": null,
      "description": "Minimum average user rating of the title (1-5 stars).",
      "minimum": 1,
      "maximum": 5
    },
    "sort": {
      "type": "string",
      "default": "relevance",
      "description": "Result ordering. \"date_asc\" sorts by the performance date, \"price_asc\" by its cheapest ticket, \"rating_desc\" by the average rating of the title. Defaults to \"relevance\".",
      "enum": [
        "relevance",
        "date_asc",
        "price_asc",
        "rating_desc"
      ]
    },
    "page": {
      "type": "integer",
      "default": 1,
      "description": "Page number, starting at 1. Compare \"page\" with \"total_pages\" or read \"has_more\" to know whether more results exist.",
      "minimum": 1
    },
    "items_per_page": {
      "type": "integer",
      "default": 10,
      "description": "Titles per page. Defaults to 10.",
      "minimum": 1,
      "maximum": 25
    }
  }
}

Returns a single performance identified by event_id (as returned by search_events or list_performances), with its title, venue, date, price, free places and buy_url. Free places and price are a snapshot taken at "_meta.indexed_at".

{
  "type": "object",
  "properties": {
    "event_id": {
      "type": "integer",
      "description": "Performance identifier - an event_id value from search_events or list_performances results."
    }
  },
  "required": [
    "event_id"
  ]
}

Returns a single title currently on sale on Biletyna.pl, identified by artist_id (as returned by search_events). "title" holds the description, average user rating, top user reviews and the nearest performance. "cities" lists every city where the title is played - one entry per city with its buy_url, number of performances, nearest date and lowest price. Use list_performances(artist_id, city) for the individual dates.

{
  "type": "object",
  "properties": {
    "artist_id": {
      "type": "integer",
      "description": "Title identifier - the artist_id field from search_events results."
    }
  },
  "required": [
    "artist_id"
  ]
}