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
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.