SSP API-dokumentation
API for supply-side-platforme til programmatiske annonceplatforme
https://polads.eu/api/v1GET /online-advertisement/{PAID}
10.000 forespørgsler pr. minut
Ratebegrænsning håndhæves pr. SSP-token
PUT /online-advertisement/{PAID}/metrics
1.000 forespørgsler pr. minut
Tælles pr. SSP-token og adskilt fra label-endpointet, så indberetning af målinger aldrig tærer på dine label-forespørgsler
/online-advertisement/{PAID}📊 Kompakt label-format
Dette endpoint returnerer en kompakt, EU-kompatibel gennemsigtighedslabel egnet til visning sammen med online-annoncer. Virker kun for annoncer med medium = "online".
Eksempel på request
curl -X GET "https://polads.eu/api/v1/online-advertisement/ABC12" \
-H "Authorization: Bearer YOUR_SSP_TOKEN" \
-H "Accept: application/json"Response-eksempel
{
"text": "Politisk Reklame - ACME Corp - Folketingsvalg - polads.eu/ABC12",
"link": "https://polads.eu/ABC12",
"PAID": "ABC12"
}Response-felter
Anvendelseseksempel
Vis labelen på din platform:
<a href="[link]" target="_blank" rel="noopener">
[text]
</a>/online-advertisement/{PAID}/metricsDit SSP-token skal have rettigheden metrics:write. En administrator slår den til på det token, du allerede bruger, så der udstedes intet nyt token.
Send de løbende totaler siden annoncen blev offentliggjort, aldrig ændringen siden din seneste levering. Hver levering erstatter de tidligere tal, så det ændrer intet at sende de samme totaler igen.
Du kan indberette tal for enhver offentliggjort annonce, uanset hvilken udgiver den tilhører. Tallene vises i dens offentlige gennemsigtighedsmeddelelse sammen med datoen for den seneste indberetning.
Eksempel på request
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}'Request-felter
Begge felter er obligatoriske, og hvert skal være et helt tal fra 0 til 2147483647.
Response-eksempel
{
"viewsCount": 15000,
"engagementsCount": 320,
"engagementMetricsUpdatedAt": "2026-10-12T08:30:00.000Z"
}Fejlrespons fra dette endpoint
401 INVALID_TOKEN
Authorization-headeret mangler, eller tokenet er ukendt, tilbagekaldt eller et partnertoken. I begge tilfælde er koden 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
Tokenet er gyldigt, men har ikke fået rettigheden metrics:write. Bed din administrator om at slå den til.
{
"error": "This token is not authorised to write metrics. Required scope: metrics:write.",
"code": "INSUFFICIENT_SCOPE"
}404 NOT_FOUND
Ingen offentliggjort annonce matcher dette PA-ID. Som på label-endpointet svarer en annonce også 404, hvis udgiveren endnu ikke har godkendt den, eller hvis dens publiceringsdato ligger ude i fremtiden.
{
"error": "Advertisement not found",
"code": "NOT_FOUND"
}409 METRICS_NOT_APPLICABLE
Annoncen falder uden for det område, engagementstal er defineret for. Annex II note 15 dækker en online- eller native-annonce, der har brugt målretning eller leveringsteknikker, og som er begyndt at køre. Der skrives ingenting.
{
"error": "Engagement metrics do not apply to this notice",
"code": "METRICS_NOT_APPLICABLE"
}400 INVALID_METRICS
Forespørgselsindholdet er ikke gyldig JSON, eller de to tal mangler, er negative eller ikke hele tal. Svaret oplyser, hvad der fejlede.
{
"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
Grænsen pr. token blev overskredet. Svaret indeholder X-RateLimit-Limit, X-RateLimit-Remaining og 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
64-tegns hexadecimal streng (256-bit entropi)
Token-håndtering
SSP-tokens administreres kun af systemadministratorer. Kontakt din administrator for at få et token.
Intet abonnement er relevant
Et SSP-token udstedes til en integrator og ikke til en udgiver, så det har ingen udgiverkonto, og der er intet abonnement at kontrollere. I modsætning til partner-API’et afhænger intet her af et abonnement. Et partnertoken afvises på dette endpoint med 401, og et SSP-token afvises på partner-endpointene på samme måde.
Hvornår endpointet svarer 404
Annoncen slås op efter samme synlighedsregel som det offentlige register. En annonce, der endnu ikke er bekræftet, som udgiveren endnu ikke har godkendt, eller hvis publiceringsdato ligger ude i fremtiden, svarer 404. En 404 er derfor ikke bevis for, at et PA-ID er forkert.
Endepunktet ovenfor returnerer selve mærkatteksten på én linje, til en mærkat din egen platform tegner. Mærket returnerer en færdig, interaktiv meddelelse, som du placerer ved siden af annoncen i en iframe. Begge beskriver den samme gennemsigtighedsmeddelelse.
Én URL pr. version
Demoens knapper svarer én til én til disse parametre, så du kan vælge på demosiden og kopiere den URL, du ser.
# Hjørnemærke, kun mærket
GET https://polads.eu/badge/{PA-ID}
# Hjørnemærke med tekst
GET https://polads.eu/badge/{PA-ID}?variant=labelled
# Synlig mærkatstribe
GET https://polads.eu/badge/{PA-ID}?layout=labelHvad hver parameter gør, og hvad det betyder at udelade den
layout=label vælger striben, udelad den for hjørnemærket. variant=labelled får det lukkede mærke til at vise sin tekst, udelad den for kun mærket. w og h angiver den plads, mærket sidder i, og afgør, hvordan det tilpasser sig på lidt plads. Udelader du dem, går mærket ud fra, at der er plads, hvilket passer til standardformaterne.
hover=0 er til demoen, ikke til din side
Den fremtvinger visningen uden hover, så demoen kan vise touch-versionen i en computerbrowser. Det rigtige mærke undersøger selv enheden. Låser du den fast, sender du den forkerte version til alle besøgende, hvis enhed siger noget andet.
Lytteren til størrelsesændring er påkrævet
Hjørnemærket indlæses i 32 gange 32, så det dækker så lidt af annoncen som muligt, og beder derefter siden om plads, når det åbner. Uden lytteren kan det slet ikke åbne. Mærkatstriben klarer sig bedre og bliver kun beskåret ved smalle bredder.
Kun for en offentliggjort meddelelse
Mærket leveres, når meddelelsen er bekræftet, godkendt af udgiveren og forbi sin startdato. Et embargoeret eller ikke-godkendt PA-ID svarer 404 efter hensigten, ikke på grund af en fejl.
401 Uautoriseret
{
"error": "Invalid or revoked SSP API token."
}{
"error": "Missing or invalid Authorization header. Expected: Bearer <token>"
}400 Ugyldig anmodning
Annoncen blev fundet, men dens medie er ikke online. Svaret returnerer den faktiske medieværdi, for eksempel print. Et manglende eller ukendt PA-ID giver i stedet 404.
{
"error": "This endpoint is only for online advertisements",
"medium": "print"
}404 Ikke fundet
{
"error": "Advertisement not found"
}429 Ratebegrænsning overskredet
{
"error": "Rate limit exceeded",
"limit": 10000,
"remaining": 0,
"reset": "2026-05-14T15:14:00.000Z"
}Dette er API-version v1, og hvert svar oplyser det i et X-API-Version-header. Brydende ændringer udgives på en ny sti frem for at ændre denne. Et v1-endpoint lukkes ikke ned uden et Deprecation-header mindst 90 dage før, jf. RFC 8594.
Maskinlæsbar specifikation
Det fulde OpenAPI 3.1-dokument findes på /api/docs. Peg Postman, Swagger UI eller en klientgenerator direkte derhen frem for at skrive denne side af.
https://polads.eu/api/docs