Die API · das eigentliche Produkt

Dieselben Ergebnisse, Ihre Oberfläche.

Eine REST-Schnittstelle mit JSON-Antworten, gebaut für Aufrufe von Server zu Server. Sie liefert dieselben Ergebnisse wie das Widget, nur ohne vorgegebene Oberfläche. Darstellung, Kanal und Takt bestimmen Sie selbst.

Endpunkte

Vier Endpunkte, mehr braucht es nicht

Endpunkt Zweck
GET /api/pur/items Beiträge zu einem Ort, Umkreis und einer oder mehreren Rubriken
GET /api/pur/categories alle wählbaren Rubriken mit Unterkategorien
GET /api/pur/places?q=… Ortssuche (Ortschaft, Gemeinde, Bezirk, Bundesland)
GET /api/pur/usage Kontingent und Tagesverbrauch des eigenen Schlüssels

Abfragen

Parameter für /items

Parameter Wirkung
place Mittelpunkt: ein beliebiger Ort in Österreich
radius_km Umkreis 0–100 km; bei 0 nur der Ort selbst und seine Ortschaften
category bis zu 10 Rubriken je Abruf, zusammengeführt und ohne Doppelte
subcategory Eingrenzung auf eine Unterkategorie
date Veranstaltungszeitraum: heute, morgen, Wochenende, Daueraktionen
since / until Erscheinungszeitraum, zum Beispiel „alles seit dem letzten Abruf“
audience, audience_mode Zielgruppen, wahlweise eine davon oder alle
secondary_places auch Beiträge, in denen der Ort nur Nebenort ist
story_broker Story-Bündelung ein oder aus
limit / offset seitenweise, bis 100 Beiträge je Seite

Beispiel

Familien-Veranstaltungen am Wochenende rund um Mödling

GET /api/pur/items?place=
    &radius_km=20
    &category=events
    &date=weekend
    &audience=audience.families
X-Api-Key: pur_…

Die Antwort enthält Veranstaltungen am kommenden Wochenende im Umkreis von 20 km um Mödling, die für Familien interessant sind. Jede Veranstaltung kommt mit Termin, Ort, Entfernung und Quelle.

Antwort je Beitrag

Titel und Linkzum Original, Medium mit Symbol, Erscheinungsdatum
Teaser und Bildüber den Proxy, mit Breite und Höhe, je nach Rechten der Quelle
Ort und EntfernungEntfernung in km zum abgefragten Mittelpunkt
VeranstaltungsterminBeginn, Ende, ganztägig
Rubrikenmit Score und Konfidenz, damit Sie eigene Schwellen setzen können
StoryStory-Kennung, Zahl der weiteren Quellen und die Quellen selbst

Betrieb

Sicher, berechenbar, ohne Überraschungen

Sicherheit

Der Schlüssel gehört nur in den Header (X-Api-Key oder Bearer), nie in die URL. Die API sendet bewusst keine CORS-Header, der Schlüssel kann also nicht versehentlich in einer Website landen.

Zwischenspeicher

Wiederholte Abfragen kommen aus dem Cache und kosten nichts. Je Abruf lässt sich eine frische Berechnung erzwingen.

Faire Abrechnung über Credits

Ein Credit je Rubrik plus einer je gelieferten Beitrag. Kontingent und Verbrauch sind jederzeit über /usage abrufbar.

Klare Fehler

400 bei falschen Parametern (mit Hinweis, was richtig wäre), 401 bei fehlendem oder ungültigem Schlüssel, 402 bei aufgebrauchtem Kontingent, 429 bei zu vielen Abrufen. Einen stillen Leerlauf gibt es nicht.

Ihre Sperrliste gilt überall

Ein Beitrag, den Sie ausgeblendet haben, kommt auch über die API nicht wieder.

Preise auf Anfrage

Das Kontingent richten wir nach Ihrem Bedarf ein. Sprechen Sie uns an.