SSP API-Dokumentation
Supply-Side-Plattform-API für programmatische Werbeplattformen
https://polads.eu/api/v1GET /online-advertisement/{PAID}
10.000 Anfragen pro Minute
Ratenbegrenzung pro SSP-Token erzwungen
PUT /online-advertisement/{PAID}/metrics
1.000 Anfragen pro Minute
Pro SSP-Token gezählt, getrennt vom Etiketten-Endpunkt, sodass das Melden von Kennzahlen nie Ihre Etikettenanfragen aufbraucht
/online-advertisement/{PAID}📊 Kompaktes Etikettenformat
Dieser Endpunkt gibt ein kompaktes, EU-konformes Transparenzetikett zurück, das zur Anzeige neben Online-Werbung geeignet ist. Funktioniert nur für Anzeigen mit medium = „online“.
Beispielanfrage
curl -X GET "https://polads.eu/api/v1/online-advertisement/ABC12" \
-H "Authorization: Bearer YOUR_SSP_TOKEN" \
-H "Accept: application/json"Response-Beispiel
{
"text": "Politisk Reklame - ACME Corp - Folketingsvalg - polads.eu/ABC12",
"link": "https://polads.eu/ABC12",
"PAID": "ABC12"
}Antwortfelder
Verwendungsbeispiel
Zeigen Sie das Label auf Ihrer Plattform an:
<a href="[link]" target="_blank" rel="noopener">
[text]
</a>/online-advertisement/{PAID}/metricsIhr SSP-Token benötigt die Berechtigung metrics:write. Ein Administrator schaltet sie für das Token frei, das Sie bereits verwenden, sodass kein neues Token ausgestellt wird.
Senden Sie die laufenden Gesamtwerte seit der Veröffentlichung der Anzeige, niemals die Veränderung seit Ihrer letzten Übermittlung. Jede Übermittlung ersetzt die vorherigen Zahlen, sodass ein erneutes Senden derselben Gesamtwerte nichts ändert.
Sie können Zahlen für jede veröffentlichte Anzeige melden, gleich welchem Herausgeber sie gehört. Die Zahlen erscheinen in ihrer öffentlichen Transparenzbekanntmachung zusammen mit dem Datum, an dem sie zuletzt gemeldet wurden.
Beispielanfrage
curl -X PUT "https://polads.eu/api/v1/online-advertisement/ABC12/metrics" \
-H "Authorization: Bearer YOUR_SSP_TOKEN" \
-H "Content-Type: application/json" \
-d '{"viewsCount": 15000, "engagementsCount": 320}'Anfragefelder
Beide Felder sind Pflichtfelder, jeweils eine ganze Zahl von 0 bis 2147483647.
Response-Beispiel
{
"viewsCount": 15000,
"engagementsCount": 320,
"engagementMetricsUpdatedAt": "2026-10-12T08:30:00.000Z"
}Fehlerantworten dieses Endpunkts
401 INVALID_TOKEN
Der Authorization-Header fehlt, oder das Token ist unbekannt, widerrufen oder ein Partner-Token. In beiden Fällen lautet der Code INVALID_TOKEN.
{
"error": "Missing or invalid Authorization header. Expected: Bearer <token>",
"code": "INVALID_TOKEN"
}{
"error": "Invalid or revoked SSP API token.",
"code": "INVALID_TOKEN"
}403 INSUFFICIENT_SCOPE
Das Token ist gültig, hat aber die Berechtigung metrics:write nicht erhalten. Bitten Sie Ihren Administrator, sie freizuschalten.
{
"error": "This token is not authorised to write metrics. Required scope: metrics:write.",
"code": "INSUFFICIENT_SCOPE"
}404 NOT_FOUND
Keine veröffentlichte Anzeige passt zu dieser PA-ID. Wie beim Etiketten-Endpunkt ergibt auch eine Anzeige, die ihr Herausgeber noch nicht freigegeben hat oder deren Veröffentlichungsbeginn noch in der Zukunft liegt, 404.
{
"error": "Advertisement not found",
"code": "NOT_FOUND"
}409 METRICS_NOT_APPLICABLE
Die Anzeige liegt außerhalb des Bereichs, für den Interaktionszahlen definiert sind. Annex II Anmerkung 15 erfasst eine Online- oder Native-Anzeige, die Targeting oder Auslieferungstechniken genutzt hat und bereits läuft. Es wird nichts geschrieben.
{
"error": "Engagement metrics do not apply to this notice",
"code": "METRICS_NOT_APPLICABLE"
}400 INVALID_METRICS
Der Anfragetext ist kein gültiges JSON, oder die beiden Zahlen fehlen, sind negativ oder keine ganzen Zahlen. Die Antwort nennt, was fehlgeschlagen ist.
{
"error": "Invalid engagement metrics",
"code": "INVALID_METRICS",
"issues": [
{
"path": "viewsCount",
"message": "Too small: expected number to be >=0"
}
]
}{
"error": "Invalid request body",
"code": "INVALID_METRICS"
}429 RATE_LIMITED
Das Limit pro Token wurde überschritten. Die Antwort enthält X-RateLimit-Limit, X-RateLimit-Remaining und X-RateLimit-Reset.
{
"error": "Rate limit exceeded",
"code": "RATE_LIMITED",
"limit": 1000,
"remaining": 0,
"reset": "2026-05-14T15:14:00.000Z"
}Header-Format
Authorization: Bearer YOUR_SSP_TOKENToken-Format
Hexadezimale Zeichenfolge mit 64 Zeichen (256-Bit-Entropie)
Token-Verwaltung
SSP-Tokens werden nur von Systemadministratoren verwaltet. Wenden Sie sich an Ihren Administrator, um ein Token zu erhalten.
Kein Tarif ist anwendbar
Ein SSP-Token wird an einen Integrator und nicht an einen Herausgeber ausgegeben, es gehört also zu keinem Herausgeberkonto und es gibt keinen Tarif zu prüfen. Anders als bei der Partner-API hängt hier nichts von einem Abonnement ab. Ein Partner-Token wird an diesem Endpunkt mit 401 abgewiesen, und ein SSP-Token wird an den Partner-Endpunkten genauso abgewiesen.
Wann der Endpunkt 404 zurückgibt
Die Anzeige wird über dieselbe Sichtbarkeitsregel aufgelöst wie das öffentliche Register. Eine Anzeige, die noch nicht bestätigt ist, die der Herausgeber noch nicht freigegeben hat oder deren Veröffentlichungsbeginn noch in der Zukunft liegt, ergibt 404. Ein 404 ist daher kein Beleg dafür, dass eine PA-ID falsch ist.
Der Endpunkt oben liefert den einzeiligen Kennzeichnungstext für eine Kennzeichnung, die Ihre eigene Plattform zeichnet. Das Kennzeichen liefert einen fertigen, interaktiven Hinweis, den Sie als iframe neben die Werbung setzen. Beide beschreiben denselben Transparenzhinweis.
Eine URL pro Version
Die Bedienelemente der Demo entsprechen diesen Parametern eins zu eins, Sie können also auf der Demoseite auswählen und die angezeigte URL kopieren.
# Eckabzeichen, nur die Marke
GET https://polads.eu/badge/{PA-ID}
# Eckabzeichen mit Beschriftung
GET https://polads.eu/badge/{PA-ID}?variant=labelled
# Dauerhaft sichtbarer Kennzeichnungsstreifen
GET https://polads.eu/badge/{PA-ID}?layout=labelWas jeder Parameter bewirkt und was das Weglassen bedeutet
layout=label wählt den Streifen, ohne ihn erscheint das Eckabzeichen. variant=labelled zeigt die Beschriftung am geschlossenen Abzeichen, ohne ihn nur die Marke. w und h geben den Platz an, in dem das Abzeichen sitzt, und bestimmen, wie es sich bei wenig Platz anpasst. Ohne sie geht das Abzeichen von ausreichend Platz aus, was für die Standardformate richtig ist.
hover=0 gehört zur Demo, nicht auf Ihre Seite
Es erzwingt die Darstellung ohne Hover, damit die Demo die Touch-Version im Desktop-Browser zeigen kann. Das echte Abzeichen prüft das Gerät selbst. Wer den Wert festschreibt, liefert allen Besuchenden mit abweichendem Gerät die falsche Version.
Der Empfänger für die Größenmeldung ist erforderlich
Das Eckkennzeichen lädt mit 32 mal 32, damit es so wenig wie möglich vom Werbemittel verdeckt, und bittet die Seite beim Öffnen um Platz. Ohne den Empfänger lässt es sich gar nicht öffnen. Der Kennzeichnungsstreifen ist gutmütiger und wird nur bei schmalen Breiten abgeschnitten.
Nur für einen veröffentlichten Hinweis
Das Kennzeichen wird ausgeliefert, sobald der Hinweis bestätigt, vom Anbieter freigegeben und sein Startdatum erreicht ist. Eine gesperrte oder nicht freigegebene PA-ID antwortet absichtlich mit 404, nicht wegen eines Fehlers.
401 Nicht autorisiert
{
"error": "Invalid or revoked SSP API token."
}{
"error": "Missing or invalid Authorization header. Expected: Bearer <token>"
}400 Ungültige Anfrage
Die Anzeige wurde gefunden, aber ihr Medium ist nicht online. Die Antwort liefert den tatsächlichen Medienwert, zum Beispiel print. Eine fehlende oder unbekannte PA-ID liefert stattdessen 404.
{
"error": "This endpoint is only for online advertisements",
"medium": "print"
}404 Nicht gefunden
{
"error": "Advertisement not found"
}429 Ratenlimit überschritten
{
"error": "Rate limit exceeded",
"limit": 10000,
"remaining": 0,
"reset": "2026-05-14T15:14:00.000Z"
}Dies ist API-Version v1, und jede Antwort sagt das in einem X-API-Version-Header. Brechende Änderungen erscheinen unter einem neuen Pfad, statt diesen zu ändern. Ein v1-Endpunkt wird nicht abgeschaltet, ohne dass mindestens 90 Tage vorher ein Deprecation-Header gesetzt wird, gemäß RFC 8594.
Maschinenlesbare Spezifikation
Das vollständige OpenAPI-3.1-Dokument wird unter /api/docs ausgeliefert. Richten Sie Postman, Swagger UI oder einen Client-Generator direkt darauf, statt diese Seite abzuschreiben.
https://polads.eu/api/docs