API documentation — ClassicalBot

Quickstart

The API is public: no account or API key is required. Requests use https://classicalbot.com/api/v1 and return JSON.

curl 'https://classicalbot.com/api/v1/concerts?country_code=CZ&page_size=2'

Filter by country to get started, or look up a city, performer or venue below to find its ID.

{
  "source": null,
  "concerts": [
    {
      "id": "123",
      "title": "Illustrative concert",
      "date": "2027-06-12",
      "time": "19:30:00",
      "city": "Prague",
      "country_code": "CZ",
      "venue_name": null,
      "buy_url": null
    }
  ],
  "pagination": {
    "page": 1,
    "page_size": 2,
    "total": 1,
    "total_pages": 1,
    "all": false,
    "next": null
  },
  "generated_at": "2027-06-01T12:00:00Z"
}

Concerts

GET /api/v1/concerts

Find upcoming concerts. Use at least one filter; results must match all supplied filters.

curl 'https://classicalbot.com/api/v1/concerts?country_code=CZ&page_size=2'

Find cities

GET /api/v1/cities

Search cities by name. Use the returned ID as city_id.

curl 'https://classicalbot.com/api/v1/cities?q=prague&country_code=CZ'

Find performers

GET /api/v1/performers

Search performers by name. Use the returned ID as performer_id.

curl 'https://classicalbot.com/api/v1/performers?q=mozart&has_upcoming=true'

Find venues

GET /api/v1/venues

Search venues by name. Use the returned ID as venue_id.

curl 'https://classicalbot.com/api/v1/venues?q=hall&country_code=GB'

Concert response reference

Missing values are null or empty arrays. IDs and prices are strings.

artists

Performer names, separated by semicolons.

venue_name

Venue or hall name.

state

Currently unavailable.

venue_address

Venue address.

buy_url

Ticket or reservation link.

id

ClassicalBot concert ID.

event_url

Concert page URL.

event_status

Concert status. Values: scheduled, cancelled, postponed, rescheduled.

last_verified_at

When the concert was last verified.

country_code

Two-letter country code.

city_id

ClassicalBot city ID.

venue_id

ClassicalBot venue ID.

parent_venue_name

Parent venue or building name.

longitude

Venue longitude.

programme

Programme summary.

programme_items

Works and their composers.

Fields in programme_items

id

title

programme_label

catalogue_number

composer

Fields in composer

id

name

composers

Composers featured in the concert.

Fields in composers

id

name

performers

Performers and their roles.

Fields in performers

id

name

kind

Values: person, ensemble.

roles

instruments

voice_type

character

ensemble

qualifier

identity_url

price_items

Price offers, currencies and conditions.

Fields in price_items

id

kind

Values: exact, from, range.

price_type

Values: admission, fee, suggested_donation.

amount

amount_max

currency

category

audience

conditions

basis

admission_type

Admission category.

booking_kind

Booking method. Values: purchase, reservation, .

booking_status

Booking availability. Values: unknown, on_sale, not_yet_on_sale, sold_out, box_office_only, not_required, .

on_sale_at

When booking opens.

source_id

ClassicalBot source ID.

source_event_urls

Concert links from its sources.

Limits

The API allows 60 requests per minute per IP, including up to five requests with all=true. On HTTP 429, wait the number of seconds in Retry-After before retrying.

Results are cached for up to two minutes. generated_at shows when the response data was loaded.

Understanding the data

Dates, times and availability

Results include concerts from today onward, using the UTC date. Concert dates use YYYY-MM-DD and times use local HH:mm:ss. Other timestamps are in UTC.

Check event_status for cancellations or schedule changes. Missing prices do not mean free admission.

IDs and search

Use the IDs returned by the city, performer and venue searches. Keep them as strings.

Search matches part of a name, ignoring case and accents. Add has_upcoming=true to find only results with upcoming concerts.

Sources

Use url to get concerts from a source website.

When registration is enabled, requesting a new source URL queues it for processing. Otherwise, an unknown source returns HTTP 404.

HTTP 202 means the source is still being processed. Wait 60 seconds before checking again.

Need help with an integration? Contact us.