Opvoedinformatie Nederland Content API
Laatst gewijzigd op: 10 februari 2020
Algemeen
Opvoedinformatie Nederland biedt landelijk gevalideerde content aan op het gebied van opgroeien, opvoeden en gezondheid. Door de combinatie van deze content wordt de betrouwbare informatie op een prettige en effectieve manier toegankelijk voor ouders en opvoeders. Opvoedinformatie Nederland heeft de publieke verantwoordelijkheid voor het onderdeel ‘content’. Dit document geeft een toelichting op het gebruik en de mogelijkheden van de API dat wordt aangeboden om deze content te ontsluiten.
Content
De landelijke database wordt via Opvoedinformatie Nederland gehost en kan door een derde partij worden opgehaald via onze API.
Gebruikersvoorwaarden
Aan het gebruik van de API stelt Opvoedinformatie Nederland voorwaarden die je accepteert bij het gebruik van de API. De voorwaarden zijn na te lezen op Opvoedinformatie.nl.
Toegang en beveiliging
De content is alleen toegankelijk met een API-Token. Heb je nog geen token? Vraag deze dan bij ons aan.
Vragen?
Alle informatie over de technische ontwikkelingen vind je op deze informatiepagina. Neem bij vragen contact op via contact@opvoedinformatie.nl of 088-11 80 200. Vermeld hierbij het IP-adres waarvandaan je de API benaderd.
Responsetijden
Wij streven er naar om je vraag binnen 8 (kantoor)uren te beantwoorden.
Inhoud
- Requests
- End-points
- Navigatiestructuur
- Koppelteksten
- Properties van een contentobject
- Links in de content
- Afbeeldingen en video’s in de content
- Het gebruik van beeldverhalen
Requests
De basis URL van de REST API van Opvoedinformatie Nederland is als volgt:
https://api.opvoedinformatie.nl/v1/
Bij elk request dienen er twee HTTP-requestheaders meegestuurd te worden, genaamd ‘Authorization’ en ‘ConsumerReference’.
De Authorization-header moet de API-token bevatten met een Bearer-prefix. De ConsumerReference-header moet een unieke referentie bevatten voor welke klant de API op dat moment benaderd wordt. De waarde van deze header mag zelf bepaald worden, maar moet uniek per klant zijn.
GET /v1/{endpoint} HTTP/1.1
Host: https://api.opvoedinformatie.nl
Authorization: Bearer {API-Token}
ConsumerReference: Klantnaam
Endpoints
De API biedt verschillende endpoints om informatie op te halen welke hierna beschreven worden. Alle API-responses zijn in JSON-formaat.
/collections
De content is onderverdeeld in collecties en elke collectie is voorzien van een keurmerk dat onder de content getoond dient te worden. Zie hiervoor de gebruiksvoorwaarden.
De collections-endpoint geeft een array van contentcollecties terug die beschikbaar zijn.
GET /v1/collections HTTP/1.1
Host: https://api.opvoedinformatie.nl
Authorization: Bearer {API-Token}
ConsumerReference: Klantnaam
De response heeft het volgende formaat:
[
{
"id": 1,
"collection": "Opvoedencontent",
"qualityMark: {
"url": "https://www.opvoeden.nl/keurmerk/",
"text": "Opvoedinformatie Nederland zorgt er met ouders en deskundigen uit de wetenschap en praktijk voor dat deze informatie betrouwbaar en actueel blijft."
"imageAlt": "Het keurkmerk van de betrouwbare opvoedinformatie van Opvoedinformatie Nederland"
"imageUrl": "https://content.opvoedinformatie.nl/images/keurmerk-opvoedencontent",
}
},
{
"id": 2,
"collection": "Jongerencontent",
"qualityMark: {
"url": "https://www.infovoorjou.nl/keurmerk/",
"text": "Opvoedinformatie Nederland zorgt er met jongeren en deskundigen uit de wetenschap en praktijk voor dat deze informatie betrouwbaar en actueel blijft."
"imageUrl": "https://content.opvoedinformatie.nl/images/keurmerk-jongerencontent",
"imageAlt": "Het keurkmerk van de betrouwbare opvoedinformatie van Opvoedinformatie Nederland"
}
},
{
"id": 3,
"collection": "Kindercontent",
"qualityMark: {
"url": "https://www.infovoorkinderen.nl/keurmerk/",
"text": "Opvoedinformatie Nederland zorgt er met kinderen en deskundigen voor dat deze informatie betrouwbaar en actueel blijft."
"imageUrl": "https://content.opvoedinformatie.nl/images/keurmerk-kindercontent",
"imageAlt": "Het keurkmerk van de betrouwbare opvoedinformatie van Opvoedinformatie Nederland"
}
}
]
/content-types
In de content zijn verschillende typen content aanwezig zoals artikelen en beeldverhalen. Je kunt de content per type ophalen. Het type artikel spreekt voor zich. Klik hier voor meer informatie over beeldverhalen.
De content-types-endpoint geeft een array van contenttypes terug.
GET /v1/content-types HTTP/1.1
Host: https://api.opvoedinformatie.nl
Authorization: Bearer {API-Token}
ConsumerReference: Klantnaam
De response heeft het volgende formaat:
[
{
"id": 1,
"type": "Artikel"
},
{
"id": 2,
"type": "Beeldverhaal"
}
]
/language-levels
Taalniveaus zeggen iets over het leesniveau dat nodig is om de content te kunnen begrijpen. Beeldverhalen zijn voor laaggeletterden en is daarom op taalniveau A1 geschreven. De kindercontent is van een iets hoger niveau: A2. De jongeren- en de opvoedencontent is geschreven op B1 niveau.
De language-levels-endpoint geeft een array van taalniveaus terug.
GET /v1/language-levels HTTP/1.1
Host: https://api.opvoedinformatie.nl
Authorization: Bearer {API-Token}
ConsumerReference: Klantnaam
De response heeft het volgende formaat:
[
{
"id": 1,
"languageLevel": "A1"
},
{
"id": 2,
"languageLevel": "A2"
},
{
"id": 3,
"languageLevel": "B1"
}
]
/audiences
Content kan voor verschillende doelgroepen geschreven zijn. Daarom kun je de content ophalen op basis van doelgroep.
De audiences-endpoint geeft een array van doelgroepen terug. Content kan meerdere doelgroepen hebben.
GET /v1/audiences HTTP/1.1
Host: https://api.opvoedinformatie.nl
Authorization: Bearer {API-Token}
ConsumerReference: Klantnaam
De response heeft het volgende formaat:
[
{
"id": 1,
"audience": "Aanstaande ouders"
},
{
"id": 2,
"audience": "Jongeren (12-18)"
},
{
"id": 3,
"audience": "Kinderen (8-12)"
},
{
"id": 4,
"audience": "Mensen met kinderwens"
},
{
"id": 5,
"audience": "Ouders"
}
]
/subjects
De content is getagd met meerdere taxonomietermen (onderwerpen) en kan opgehaald worden op basis van deze termen. De termen zeggen iets over de inhoud van de content.
De subjects-endpoint geeft een array van onderwerpen terug. Content kan meerdere subjects hebben.
GET /v1/subjects HTTP/1.1
Host: https://api.opvoedinformatie.nl
Authorization: Bearer {API-Token}
ConsumerReference: Klantnaam
De response heeft het volgende formaat:
[
{
"id": 1,
"subject": "Levensfase",
"parentId": null,
"synonyms": []
},
{
"id": 2,
"subject": "Baby",
"parentId": 1,
"synonyms": []
},
{
"id": 3,
"subject": "Baby 0",
"parentId": 2,
"synonyms": []
},
{
"id": 4,
"subject": "Baby 1",
"parentId": 2,
"synonyms": []
},
{
"id": 5,
"subject": "Peuter",
"parentId": 1,
"synonyms": []
},
... etc
]
De onderwerpen waarmee content getagged kan zijn, staan in een hiërarchische structuur van maximaal 3 lagen diep. De parentId property geeft aan welk ander subject object de “parent” is. Als in een contentquery een onderwerp gebruikt wordt van een hoger niveau dan wordt ook content gematched die getagged zijn met onderwerpen op een lager gelegen niveau. Bijvoorbeeld onder het onderwerp “Baby” zijn twee dieper gelegen onderwerpen aanwezig genaamd “Baby 0” en “Baby 1”. Indien er in de contentquery gebruik wordt gemaakt van het onderwerp “Baby” dan zal ook content gematched worden die getagged is met “Baby 0” of “Baby 1”.
De synonyms property is een array van strings van synoniemen voor het onderwerp.
/content/{id}
De content/{id}-endpoint wordt gebruikt om content op te halen aan de hand van een specifiek identificatienummer.
GET /v1/content/{id} HTTP/1.1
Host: https://api.opvoedinformatie.nl
Authorization: Bearer {API-Token}
ConsumerReference: Klantnaam
De response heeft het volgende formaat:
{
"identifier": 123,
"title": "Titel van de content",
"abbreviation": "De verkorte titel van de content",
"type": "Artikel",
"authority": "Opvoedinformatie Nederland",
"publisher": "Opvoedinformatie Nederland",
"issued": "2018-10-25T15:04:25.81071",
"modified": "2018-10-25T15:04:25.81071",
"dateAccepted": "2018-10-25T15:04:25.81071",
"available": {
"start": "2018-10-25T15:04:25.81071",
"end": null
},
"sources": null,
"abstract": "De samenvatting van de content",
"extent": "Aantal woorden in de content",
"format": "text/html",
"subject": [
{
"id": 1,
"subject": "Onderwerp 1",
"parentId": null,
"synonyms": []
},
{
"id": 2,
"subject": "Onderwerp 2",
"parentId": null,
"synonyms": []
}
],
"audience": [
"Doelgroep 1",
"Doelgroep 2"
],
"language": "nl_NL",
"languageLevel": "B1",
"collection": "Opvoedencontent",
"parentIdentifier": 1,
"hierarchicalOrder": 3,
"structuralContent": false,
"canonicalUrl": "https://www.opvoeden.nl/url-van-content",
"content": {
"body": "lorem ipsum"
}
}
De properties in de response worden verderop beschreven.
/content
De content-endpoint wordt gebruikt om content op te halen aan de hand van een contentquery. Een contentquery is een zoekopdracht in JSON-formaat en wordt als Request Body in een POST-request naar de content-endpoint gestuurd. Voor dit request dient ook de “Content-Type” HTTP-header aanwezig te zijn met als waarde “application/json”.
POST /v1/content HTTP/1.1
Host: https://api.opvoedinformatie.nl
Content-Type: application/json
Authorization: Bearer {API-Token}
ConsumerReference: Klantnaam
{
"collections": ["Opvoedencontent"],
"audiences": ["Ouders"],
"languageLevels": ["B1"],
"types": ["Artikel"],
"subjects":
[
["Baby 0", "Veiligheid"],
["Ouderschap", "Veiligheid"]
]
}
In een contentquery kunnen de volgende filters gedefinieerd worden:
| collections (verplicht) | Een array van de collecties waarvan de content opgehaald moet worden. Deze property is verplicht. |
| audiences | Een array van doelgroep(en) waarvoor de content bestemd moet zijn. |
| languageLevels | Een array van taalniveaus waarin de content geschreven moet zijn. |
| types | Een array van contenttypes van de content die opgehaald moet worden. |
| subjects | Een tweedimensionale array van onderwerpen waarmee de content getagged moet zijn. Op onderwerpen in de binnenste arrays wordt een “AND” operator toegepast. Op de buitenste array wordt een “OR” operator toegepast. In bovenstaand voorbeeld wordt content opgehaald die getagged zijn met (“Baby 0” AND “Veiligheid”) OR (“Ouderschap” AND “Veiligheid”). |
| modifiedSince | De datum wanneer het object voor het laatst gewijzigd is. Wijzigingen betreffen niet alleen inhoudelijke wijzigingen in de content maar ook wijzigingen aan bijvoorbeeld de metadata of hiërarchische positie van het object zelf of één van de bovenliggende objecten. |
| includeAvailable | Een boolean die aangeeft of gepubliceerde content in het antwoord aanwezig moet zijn. Deze eigenschap staat standaard op true. |
| includeRemoved | Een boolean die aangeeft of gedepubliceerde content in het antwoord aanwezig moet zijn. Deze eigenschap staat standaard op false. Gedepubliceerde content is te herkennen aan de eigenschap “available.end”. Deze eigenschap heeft dan de datum van vandaag of een datum in het verleden. |
Op de collectionsfilter na zijn alle overige filters optioneel.
De response van de “content” endpoint is een array van objecten, waarvan het formaat gelijk is aan de endpoint “content/{id}”.
Navigatiestructuur
Wanneer je de content wilt gebruiken met een voorgedefinieerde navigatiestructuur dan maak je deze structuur met de proporties parentIdentifier en hierarchicalOrder. Zie Properties van een content object.
De structuur die je met deze properties opbouwt, is anders dan de structuur die je op Opvoeden.nl ziet. De structuur van Opvoeden.nl is samengesteld op basis van taxonomie.
Koppelteksten
De navigatiestructuur wordt opgebouwd met teksten die specifiek voor deze structuur zijn gemaakt. Je herkent deze teksten aan de propertie structuralContent die als waarde ‘true’ heeft. Zie Properties van een content object.
De teksten waarmee deze structuur is opgebouwd hebben een andere status dan de rest van de content. Alle teksten met structuralContent=true bevatten geen gevalideerde informatie en vallen daarom buiten de gebruiksvoorwaarden. Deze teksten hoef je dus niet te voorzien van een keurmerk en mag je daarom ook aanpassen.
Properties van een content object
| identifier | Het unieke identificatienummer van de content. |
| title | De titel van de content. |
| abbreviation | Afkorting van de titel van de content. |
| type | Het contenttype van de content. |
| authority | Organisatie die de wettelijke verantwoordelijkheid draagt voor de inhoud (strekking) van de content. |
| publisher | De persoon of organisatie verantwoordelijk voor het publiceren van de content. |
| issued | Datum waarop de content formeel werd vrijgegeven. |
| modified | Datum waarop de content is gemaakt of voor het laatst inhoudelijk is gewijzigd. |
| dateAccepted | Datum waarop de content op inhoud is gevalideerd. Deze datum kan afwijkend zijn van de datum waarop het object voor het laatst gewijzigd is (modified) of de publicatiedatum (available.start). Deze kunnen nieuwer dan dateAccepted zijn vanwege wijzigingen in de hiërarchische positie of bijvoorbeeld het corrigeren van typefouten. |
| available | Datum waarop of periode waarin de content wordt gepubliceerd. Deze property is een object met daarin een start- en endproperty. De endproperty kan null zijn, wat betekent dat er geen einddatum bekend is. |
| sources | Een array van bronnen (URL’s naar de bron) die aangeven op welke richtlijn/standaard/protocol de inhoud van de content is gebaseerd. |
| abstract | Samenvatting van de content. |
| extent | De omvang van de content uitgedrukt in het aantal woorden. |
| format | Het formaat van de content (text/html). |
| subject | Een array van onderwerpen van de content. |
| audience | Een array van doelgroepen voor wie de content bedoeld of nuttig is. |
| language | Taal waarin de content geschreven is. |
| languageLevel | Het taalniveau waarin de content geschreven is. (Zie http://detaalbrigade.nl/taalniveaus/). |
| collection | De contentcollectie waar de content toe behoort. |
| parentIdentifier | De ID van de bovenliggende content. Deze eigenschap heeft de waarde NULL als het de bovenste content in de hiërarchie is. |
| hierarchicalOrder | Een numerieke waarde die gebruikt kan worden om de volgorde van content te bepalen die dezelfde “parent” content hebben. |
| structuralContent | Een boolean die aangeeft of de content zogeheten structuurcontent is of gevalideerde content. True = structuurcontent. False is gevalideerde content. |
| canonicalURL | De canonical-URL van de content. Zie developers.google.com voor meer informatie. |
| content | Een object met daarin eigenschappen van de content. De inhoud van dit object verschilt per contenttype. |
| content.body | De HTML van de content van type “Artikel”. |
| content.pages | Een array van objecten (pagina’s) van content van het type “Beeldverhaal”. |
| content.pages[.id] | De unieke ID van de pagina van een beeldverhaal. |
| content.pages[x].title | De titel van de pagina van een beeldverhaal. |
| content.pages[x].ImgId | Het ID van de afbeelding behorende bij de pagina van een beeldverhaal. |
| content.pages[x].alt | De alt-tekst van de afbeelding behorende bij de pagina van een beeldverhaal. |
| content.pages[x].audioId | Het ID van het audiobestand behorende bij de pagina van een beeldverhaal. |
| content.pages[x].body | De content (plain-text) van de pagina van een beeldverhaal. |
Links in de content
De body van de content kan links bevatten naar andere content. Deze links zullen altijd in een <a> element aanwezig zijn en altijd naar de canonical URL’s van de content verwijzen. Indien de content ook op de eigen site beschikbaar is, dan kan de URL in het <a> element (de canonical-URL) eenvoudig vervangen worden door de URL waarop deze content binnen de eigen site beschikbaar is.
Indien de content waarnaar de link verwijst niet op de eigen site beschikbaar is, dan is het wellicht wenselijk om een target=”_blank” toe te voegen aan het <a>-element zodat de bezoeker niet van de eigen site verdwijnt.
Afbeeldingen en video’s in de content
Sommige content maakt gebruik van afbeeldingen en/of video’s. Deze zijn altijd omvat met een <figure> element. Indien afbeeldingen en/of video’s niet wenselijk zijn in de content op de eigen site, dan is het eenvoudig om “<figure>…</figure>” HTML-blokken te verwijderen.
De HTML-structuur van afbeeldingen en video’s is als volgt:
Afbeeldingen
<figure class="so" data-imd="123">
<header>
<h1>Titel van de afbeelding</h1>
<span>
Bron:
<a href="url-van-bron" target="_blank">bronvermelding met link</a>
</span>
</header>
<img src="https://www.opvoeden.nl/url-van-afbeelding.jpg" alt="Alt tekst">
<figcaption>Onderschrift van de afbeelding</figcaption>
</figure>
Video’s
<figure class="so" data-video="123">
<header>
<h1>Titel van de video</h1>
<span>
Bron:
<a href="url-van-bron" target="_blank">bronvermelding met link</a>
</span>
</header>
<div>
<iframe src="https://www.youtube-nocookie.com/url" allowfullscreen></iframe>
</div>
<figcaption>Onderschrift van de video</figcaption>
</figure>
Let er op dat als de afbeeldingen en/of video’s in de content op de eigen site gebruikt worden dat er dan CSS aanwezig is om de figure.so elementen de juiste vormgeving te geven. De volgende CSS kan als basis gebruikt worden. Deze CSS zorgt er tevens voor dat afbeeldingen en video’s responsive schalen.
figure.so {
border: 1px #ddd solid;
margin: 0 0 15px 0;
padding: 5px;
display: inline-block;
}
figure.so.so-video {
display: block;
}
figure.so header {
margin: 5px 3px 10px;
}
figure.so header h1 {
font-size: medium;
margin: 0 0 3px;
}
figure.so header span {
font-size: small;
}
figure.so header span a {
color: #888;
}
figure.so img {
max-width: 100%;
height: auto;
}
figure.so figcaption {
font: italic smaller sans-serif;
padding: 5px 3px 0px;
}
figure.so.so-video div {
position: relative;
display: block;
height: 0;
padding: 0 0 56.25% 0;
overflow: hidden;
}
figure.so.so-video div iframe {
position: absolute;
top: 0;
bottom: 0;
left: 0;
width: 100%;
height: 100%;
border: 0;
}
Het gebruik van beeldverhalen
Beeldverhalen kunnen op een aantal manieren gebruikt worden. De makkelijkste manier is de beeldverhalen widget, maar er kan ook gebruik worden gemaakt van de API om de data van beeldverhalen op te halen en er een eigen implementatie omheen te bouwen.
Gebruik van de beeldverhaalwidget
Om een beeldverhaal met de standaard styling te integreren in een website, zullen er twee html elementen moeten worden toegevoegd aan de website.
De head van het document
<script src="https://opvoeden.nl/plugins/beeldverhalenPlugin/public/audiobooks.js" data-styled="true"></script>
Met het attribuut data-styled=”true|false” wordt bepaald of er een generiek stylesheet wordt opgehaald, of dat de styling in eigen beheer wordt ontwikkeld. Als basis kan gebruik worden gemaakt van de generieke stylesheet, welke hier te downloaden is:
https://content.opvoedinformatie.nl/css/audiobook.css
Het is ook mogelijk om de generieke stylesheet te overrulen met eigen styles. Zorg er dan wel voor dat de eigen styles ingeladen worden na de script-tag van de widget.
De body van het document
In de body van het document kunnen meerdere beeldverhalen worden toegevoegd. Dit doe je aan de hand van de volgende code:
<div class="audiobook" id="####"></div>
De id van het html element id=”####” komt overeen met de ID van het beeldverhaal.