Partner V1 Rest API

Einführung

Damit ein Request an unsere Schnittstelle gesendet werden kann, wird ein Access Token benötigt. Der Access Token wird per E-Mail (Kontakt) zugestellt.

Gewisse Bereiche können für Regionen verfügbar bzw. nicht verfügbar sein. Dies ist von der Art der Kooperation mit Heartbeat GmbH abhängig.

Seit Juli 2017 muss anstelle des Access Token via GET parameter die Bearer Authorization Header Option gesendet werden.

Für PHP gibt es ein Partner API SDK auf GitHub.

Beispiel CURL Request:

curl -i \
-H "Accept:application/json" \
-H "Authorization: Bearer mytoken123" \
"https://api.heartbeat.gmbh/partnerV1/events"

Umgebungen

Umgebung URL
Produktion https://api.heartbeat.gmbh/partnerV1
Testing https://sandbox.api.heartbeat.gmbh/partnerV1

Request Parameter

Param Optional Beschreibung
access-token Ja Diese Methode wird nicht empfohlen! Benutzen Sie die Bearer Auth Möglichkeit anstelle des Access Token Parameters.
lang Ja Die Request-Response-Sprache mittels locale value z.B. de_CH oder en_GB. Standard ist de_CH.
_format Ja Anstelle des Accept-Headers kann der _format Parameter verwendet werden um die Art der Respone zu definieren. Verfügbare Werte sind json und xml.

Request Headers

Header Beschreibung Optionen Beispiel
Accept Definiert das Format welches zurückgegeben wird. application/json oder application/xml Accept:application/json
Authorization Stellt den Access Token zur Verfügung Bearer mytoken123 Authorization: Bearer mytoken123

Envelope

Die Schnittstellen verfügen über einen Collections Envelope mit folgenden Knoteninformationen:

Knoten Information
items Beinhaltet alle Einträge (rows/items) für den Request.
_links Enthält weiterführende Links, um beim Auslesen der Daten eine Paginationen zu ermöglichen.
_meta Die Meta Collection enthält Informationen zu: rows, page count, current page, per Page.
<response>
    <items>...</items>
    <_links>...</_links>
    <_meta>...</_meta>
</response>

Expandables

Gewisse API Endpunkte können weiterführende Daten haben, auch expand genannt. Um expand Daten anzuzeigen, mus ein GET Parameter expand eingefügt werden.

/partnerV1/pois/1?expand=tags,timetables

Mehrere expand Parameter können durch ein Komma getrennt notiert werden.

Events

https://api.heartbeat.gmbh/partnerV1/events

GET https://api.heartbeat.gmbh/partnerV1/events Gibt alle zukünftigen Events zurück. Sortiert nach Beginn des Events in absteigender Reihenfolge.
GET https://api.heartbeat.gmbh/partnerV1/events/ID Gibt alle Informationen zu einem Event aus. Diese Methode kann bspw. genutzt werden, um Stammdaten zu aktualisieren.

Beispiel Response

{
    "id": 7472,
    "start_timestamp": 1543755600,
    "start_timestamp_formated": "02.12.18, 14:00",
    "end_timestamp": 1543762800,
    "end_timestamp_formated": "02.12.18, 16:00",
    "extra_text": "",
    "origin": "https://www.heartbeat-aarau.ch/kalender/offentlicher-eintritt-aufschluss-meyerstollen-mit-fuhrung/7472",
    "event": {
        "title": "Öffentlicher Eintritt Aufschluss Meyerstollen mit Führung",
        "description": "Mit dem Aufschluss Meyerstollen unter dem Bahnhof Aarau erschliesst das Stadtmuseum den Besucherinnen und Besuchern das Werk des Frühindustriellen Rudolf Meyer Sohn, der vor 200 Jahren ein weit verzweigtes Stollensystem unter der Stadt Aarau baute. Eine kleine Ausstellung widmet sich verschiedenen Aspekten des Bauwerks, der Technik und der Geologie.  Dieser spezielle Ort wird auch für kulturelle Veranstaltungen genutzt.\r\n\r\nEingang: Bahnhof Aarau, gegenüber Bahnreisezentrum 1. UG\r\nFührung: 14.15 Uhr",
        "price": "",
        "age": null,
        "website": "http://www.stadtmuseum.ch/page/71/event/1553/eventdate/895",
        "ticket_link": "",
        "flyer": "https://api.heartbeat.gmbh/image/aufschlussbesucher_d7c34a9e.jpg",
        "pois": [
            {
                "id": 396,
                "origin": "",
                "title": "Stadtmuseum",
                "teaser_description": "Fotografie, Film und Stadtgeschichte",
                "full_description": "Die Kombination von altem Turm und modernem Erweiterungsbau ist spannende Architekturgeschichte. Im barrierefrei zugänglichen Anbau finden diverse Wechselausstellungen Raum, aktuell \"Netzwerk Schweizer Pressefotografie\", während der alte Schloss-Teil Plattform für die Dauerausstellung \"100x Aarau\" ist. Das Stadtmuseum lädt ein zur Diskussion über vergangene, aktuelle und zukünftige Entwicklungen. Die Sammlung mit 60'000 Objekten ist der Erinnerungsspeicher von Aarau. Baukultur und Stadtgeschichte werden durch Ausstellung und Vermittlung im Altbau freigelegt.",
                "street": "Schlossplatz",
                "street_nr": "23",
                "street_combined": "Schlossplatz 23",
                "zip": "5000",
                "city": "Aarau",
                "cords_lng": "8.0452879",
                "cords_lat": "47.3944274",
                "is_temp_closed": 0,
                "logo": "https://api.heartbeat.gmbh/image/logo-stadtmuseum-aarau_34e1ca8e.jpg"
            }
        ]
    }
}
    

Felder

Feld Beschreibung
idEindeutiger Datensatz identifier
start_timestampUnix Timestamp über den Start des Events.
end_timestampUnix Timestamp über das Ende des Events.
start_timestamp_formatedFormatierter Timestamp über den Start des Events.
end_timestamp_formatedFormatierter Timestamp über das Ende des Events.
extra_textEin Event kann mehrere Durchführungsdaten haben, welche jeweils eigene ergänzende Beschreibungen enthalten können. Beispiel: Eine Partyreihe, an welcher jeweils nur der DJ pro Datum unterschiedlich ist. Diese zusätzlichen Informationen werden im extra_text hinterlegt.
originOrigin Link zum Event Datensatz auf der Hearbeat Platform
event
Feld Beschreibung
titleTitel des Events
descriptionBeschreibung des Events. Kann Markdown Syntax enthalten.
pricePreisangabe, zum Beispiel Eintrittspreis. Kann mehrfache Preiseangaben enthalten.
ageInformation über das Mindesalter des Events.
websiteEine Webseite mit weiteren Informationen zum Event oder Link zum Ticketing.
flyerAdresse zum Bild des Events. Beispiel: Fyler.
pois (array)
Feld Beschreibung
originOrigin Link zum POI Datensatz auf der Hearbeat Platform
titleName des POI
teaser_descriptionSehr kurzer Teaser Text.
full_descriptionAusführliche Beschreibung des POI
streetStrasse
street_nrStrassen Nr., kann leer sein.
zipPostleitzahl
cityOrtschaft
cords_lngLNG Koordinaten
cords_latLAT Koordinaten

POI (Location)

https://api.heartbeat.gmbh/partnerV1/pois

GET https://api.heartbeat.gmbh/partnerV1/pois Gibt eine Liste von POIs aus. Sortiert nach Alphabet in absteigender Reihenfolge.
GET https://api.heartbeat.gmbh/partnerV1/pois/ID Gibt alle Infos zu einem POI aus. Diese method kann zum beispiel genutzt werden, um Stammdaten zu aktualisieren.
GET https://api.heartbeat.gmbh/partnerV1/pois/ID/events Gibt alle upcoming Events für diesen POI zurück.

Expand

images Gibt alle Teaser-Bilder anhand eines Array zu diesem POI zurück.
tags Gibt eine Liste aller Tags (Beispiele: "restaurant", "bar", "burger", "italienisch", "buergerlich") zurück, welche diesem POI zugeordnet wurden.
timetables Gibt eine Liste der Öffnungszeiten aus, welche diesem POI zugeordnet sind.
ratingAttributes Gibt eine Liste der Rating-Attribute zurück, welche diesen Tags zugewiesen wurden. Diese sind z.B. nötigen um Ratings mit Attributinformation zu speichern.
origins Gibt eine Liste mit Origin-Links zurück, um Weiterleitungen auf eine der Origin Plattformen zu machen.
virtualProperties Gibt alle angehängten Virtuellen Eigenschaften zurück.

Beispiel Response

{
    "id": 516,
    "origin": "",
    "title": "Heartbeat GmbH",
    "teaser_description": "Am Puls der Stadt",
    "full_description": "Wir digitalisieren das Analoge und machen das Virtuelle greifbar. Wir sorgen dafür, dass du genau die Informationen zur Verfügung hast, die du brauchst. \nWir erwecken Daten zum Leben.",
    "street": "Bahnhofstrasse",
    "street_nr": "102",
    "street_combined": "Bahnhofstrasse 102",
    "zip": "5000",
    "city": "Aarau",
    "cords_lng": "8.0544343",
    "cords_lat": "47.3927151",
    "is_temp_closed": 0,
    "logo": "https://api.heartbeat.gmbh/image/logo-heartbeat-gmbh_ea057f17.png"
}
        

Felder

Feld Beschreibung
idEindeutiger Datensatz Identifier
originOrigin Link zum Datensatz auf der Hearbeat Platform
titleName des POIs
teaser_descriptionSehr kurzer Teaser-Text.
full_descriptionAusführliche Beschreibung des POIs
streetStrasse
street_nrStrassen Nr., kann leer sein.
street_combinedStrasse und Nr. als eine Zeichenkette
zipPostleitzahl
cityOrtschaft
cords_lngLNG Koordinaten
cords_latLAT Koordinaten
logoPfad zum Logo
timetables (array)Expand: Beinhaltet ein mehrdimensionales Array mit dem jeweiligen Wochentag und t1,t2,t3,t4 Zeiten.
tags (array)Expand: Beinhaltet ein mehrdimensionales Array mit den Tags, welche diesem POI zugewiesen wurden. Die alias_translation kann den Alias für eine requested Fremdsprache enthalten.
ratingAttributes (array)Expand: Beinhaltet ein mehrdimensionales Array mit den Rating-Attributen, welchen den Tags angehängt wurden. Diese Daten werden gebraucht, um neue Ratings zu erstellen.
images (array)Expand: Beinhaltet ein mehrdimensionales Array mit den Teaser-Bildern zu diesem POI.
origins (array)Expand: Beinhaltet ein mehrdimensionales Array mit den Infos zu Origin-Plattformen. Zwecks Weiterleitung zur Originalplattform.

Streams

https://api.heartbeat.gmbh/partnerV1/streams

Streams beinhalten Informationen wie POIS, Veranstaltungen oder Blogs.

GET https://api.heartbeat.gmbh/partnerV1/streams Gibt alle Streams zurück, welche für diese Organisation freigegeben sind.

Beispiel Response

"items": [
    {
        "id": 2,
        "title": "Test Feed",
        "alias": "test-feed",
        "max_items": null
    },
    {
        "id": 3,
        "title": "Frontpage Feed Top",
        "alias": "frontpage-feed-top",
        "max_items": null
    },
    {
        "id": 4,
        "title": "Frontpage Feed Bottom",
        "alias": "frontpage-feed-bottom",
        "max_items": null
    }
],
GET https://api.heartbeat.gmbh/partnerV1/streams/alias Gibt alle Items für diesem stream zurück. Anstelle der ID kann alternativ (und meist einfacher) der Alias verwendet werden.

Expand

images Bilder von POIS.
image Teaser Bild von Blogs
virtualProperties Eigenschaften von Blogs und POIs. Um die Daten als Objekt mit einem identifer (anstelle eines Arrays) auszugeben, kann _object=1 als get Parameter angefügt werden.

Beispiel Response

{
    "id": "2",
    "title": "Test Feed",
    "alias": "test-feed",
    "max_items": null,
    "is_max_items_exceed_allowed_but_output_limited": "0",
    "is_hidden_items_displayed": "0",
    "items": {
        "0": {
            "id": "58",
            "stream_id": "2",
            "sort_index": "0",
            "type": "blog",
            "pk_id": "51",
            "object": {
                "id": 51,
                "identifier": "zmpz",
                "status": 2,
                "title": "Rustikal Essen im Wald",
                "teaser": "Ein Besuch im Roggenhausen",
                "text": "text",
                "publish_timestamp": 1544655600
            }
        },
        "2": {
            "id": "59",
            "stream_id": "2",
            "sort_index": "4",
            "type": "poi",
            "pk_id": "516",
            "object": {
                "id": 516,
                "origin": "",
                "title": "Heartbeat GmbH",
                "teaser_description": "Am Puls der Stadt",
                "full_description": "Wir digitalisieren das Analoge und machen das Virtuelle greifbar. Wir sorgen dafür, dass du genau die Informationen zur Verfügung hast, die du brauchst. \nWir erwecken Daten zum Leben.",
                "street": "Bahnhofstrasse",
                "street_nr": "102",
                "street_combined": "Bahnhofstrasse 102",
                "zip": "5000",
                "city": "Aarau",
                "cords_lng": "8.0544343",
                "cords_lat": "47.3927151",
                "is_temp_closed": 0,
                "logo": "https://api.heartbeat.gmbh/image/logo-heartbeat-gmbh_ea057f17.png"
            }
        },
        "3": {
            "id": "60",
            "stream_id": "2",
            "sort_index": "5",
            "type": "event",
            "pk_id": "7472",
            "object": {
                "title": "Aarauer Naturfilmtage 2019",
                "description": "Description",
                "price": "25",
                "age": null,
                "website": "",
                "ticket_link": "",
                "flyer": "https://api.heartbeat.gmbh/image/filebufferservlet_064d0de0.jpg",
                "pois": [
                    {
                        "id": 75,
                        "origin": "",
                        "title": "Naturama Aargau",
                        "teaser_description": "Modern und naturnah",
                        "full_description": "Im Naturama erwartet dich eine vollständig neue, nach modernen Gesichtspunkten gestaltete Ausstellung. Auf drei Stockwerken lernst du den Lebensraum Aargau mit ganz neuen Augen zu sehen. Temporäre Sonderausstellungen zu interessanten Themen sorgen für Abwechslung und Aktualität.",
                        "street": "Feerstrasse",
                        "street_nr": "17",
                        "street_combined": "Feerstrasse 17",
                        "zip": "5001",
                        "city": "Aarau",
                        "cords_lng": "8.0513999",
                        "cords_lat": "47.3926143",
                        "is_temp_closed": 0,
                        "logo": "https://api.heartbeat.gmbh/image/natlogo-schwarzohnehintergr_6d2ef356.png"
                    }
                ]
            }
        }
    }
}

Ratings

https://api.heartbeat.gmbh/partnerV1/ratings

POST https://api.heartbeat.gmbh/partnerV1/ratings Speichert ein neues Rating mit oder ohne Rating-Attributes. Beim Speichern wird das Rating mit der API-Organisation verknüpft, damit definiert ist, auf welcher Platform das Rating erstellt wurde.

Felder

Folgende POST informationen müssen an den API-Endpunkt gesendet werden:

Felder

Feld Beschreibung
rating intWert zwischen 1 und 10. Je höher desto besser fällt das Rating aus. (10 sehr gut, 1 = nicht gut)
poi_id intIdentifiaktions-ID des POIs.
user_client_language varchar(2)Umgebungssprache der Eingabemaske, z.B. de,fr,it,en
ratingAttributes (array) Jedes array muss enthalten:
  • attribute_id Id des attributes
  • value Wertung des Attributes: -1 Schlecht, 0 Neutral, 1 Gut
Heartbeat GmbH | 01a6095f3c45