Die Balloon Events API

Holen Sie sich kuratierte Event-Daten in Ihre App mit einer einfachen REST API. Suchen Sie nach Region, Kategorie oder Datum — und erhalten Sie sauberes, strukturiertes JSON zurück. Kein Scraping, kein Aufräumen, keine Kopfschmerzen.

Interaktive API-Dokumentation →

Die Grundlagen

Basis-URL

https://beat.balloon-events.com/api

Authentifizierung

Übergeben Sie Ihren API-Key im Api-Key-Header. Nur HTTPS.

curl -H "Api-Key: your-api-key" \
  https://beat.balloon-events.com/api/v2/balloons?per_page=10

Endpoints

Events auflisten & filtern

GET /v2/balloons

Query-Parameter:

  • q — Volltextsuche (z.B. festival)
  • category_ids — Nach Kategorie-UUIDs filtern
  • tag_ids — Nach Tag-UUIDs filtern
  • region_ids — Nach Region-UUIDs filtern
  • start_date / end_date — Zeitraum (Y-m-dTH:i:s-Format)
  • per_page — Ergebnisse pro Seite (Standard: 15)
  • page — Seitennummer

Komplexe Suche

POST /v2/balloons/filter

Für Abfragen, die für URL-Parameter zu komplex sind. Akzeptiert einen JSON-Body mit denselben Filteroptionen plus zusätzlichen Kriterien.

Einzelnes Event abrufen

GET /v2/balloons/{balloonIdOrSlug}

Vollständigen Datensatz eines Events per UUID oder URL-Slug abrufen (z.B. summer-festival-2025).

Delta-Sync

POST /v2/balloons/changes?since=2025-08-20T09:00:00Z

Erstellte, aktualisierte oder gelöschte Events seit einem Zeitstempel. Unterstützt alle Standardfilter plus:

  • topLeft / bottomRight — Geo-Bounding-Box (lat,lng)
  • mustHaveAtLeastOneImage — Nur Events mit Bildern
  • includeSoftDeleted — Gelöschte Datensätze einbeziehen

Kategorien

GET /v2/categories

Hierarchischer Kategoriebaum — kanonische Kategorien plus partnerspezifische. Nützlich für Filter-UIs.

Tags

GET /v2/tags

Kategorisierte Tags: System-, Nutzer-, allgemeine und Partner-Tags.

Orte

GET /v2/klz-locations

Orte nach Name suchen. Gibt Venue-Details mit Koordinaten zurück.

App-Metadaten

GET /v2/app/metadata

Statische Metadaten — Kategorien, Tags und Provider in einem Aufruf.

Was steckt in einem Event?

  • Name — Lokalisierte Event-Titel
  • Beschreibung — Volltext und Kurzzusammenfassungen
  • Wann — Start-/Enddatum, Uhrzeiten, Wiederholungsinfos
  • Wo — Venue, Adresse, Stadt, Region, Lat/Lng-Koordinaten
  • Bilder — URLs mit Dimensionen
  • Kategorien — Standardisierte Kategorie-Tags
  • Tags — Zusätzliche Klassifizierung
  • Veranstalter — Kontaktinfos und Organisationsdetails
  • Qualitätsscore — 0–100 Vollständigkeitsbewertung

Ideen, was Sie bauen können

  • Ihr CMS befüllen — Events planmäßig ziehen, Qualitätsscores für die besten Inhalte nutzen
  • Mobile App antreiben — Per Geo-Bounding-Box nach Nähe filtern
  • Redaktionelle Workflows bereichern — Vorgefilterte, bereinigte Event-Daten für Ihr Verbreitungsgebiet
  • Synchron bleiben — Delta-Sync für erstellte, aktualisierte und gelöschte Events nutzen
  • Event-Trends analysieren — Regionale Aktivitäten kartieren, saisonale Muster erkennen

Die Daten sind sauber — garantiert

Jedes Event durchläuft unsere Kuratierungspipeline: hunderte Quellen, normalisiert, dedupliziert, qualitätsbewertet und KI-moderiert. Sie bekommen das polierte Ergebnis.

Preise

  • Kostenlos — Perfekt zum Prototyping und für kleine Projekte
  • Standard — Produktionsreif mit höheren Limits
  • Enterprise — Individuelle Limits, SLAs und Priority-Support

API-Key holen →

Weitere Ressourcen