Edurep:Widget Endpoint
Naar navigatie springen
Naar zoeken springen
Edurep: Widget Endpoint
Voor de Widget wordt gebruik gemaakt van een JSON endpoint die ook voor het grotere publiek beschikbaar is. Deze pagina beschrijft de interfacing voor de JSON endpoint. De simple JSON endpoint wordt niet in detail uitgelegd.
Ook al staat de interface hier gespecificeerd, raden we aan om de gewenste zoekvraag via de Widget Wizard samen te stellen en aldaar te exporteren als JSON query.
|
Het gebruik van deze endpoint valt niet onder de SLS van Edurep. We zijn wel van plan om deze dienstverlening definitief te maken. |
Endpoint
- https://proxy.edurep.nl/v3/search
|
|
Dit endpoint adres kan verouderen en vervangen worden door een nieuwere versie endpoint. |
Argumenten
Een overzicht van de ondersteunde argumenten:
| naam | # | type | omschrijving |
|---|---|---|---|
| mode | 1 | string | Een der uitvoerformaten, json, simplejson, of rss. |
| query | 1 | cql query | Een zoekopdracht binnen LOM records. |
| startRecord | 0-1 | getal | De resultatenlijst wordt getoond vanaf dit record, standaard 1. |
| maximumRecords | 0-1 | getal | Het aantal records in de getoonde resultatenlijst, standaard 5, max 10. |
| x-term-drilldown | 0-1 | edurep zoekveld | Het veld waarop een term drilldown wordt gedaan voor de gevonden resultaten. |
| technicalFormats | 0-1 | een gemapt technisch formaat | Filtert de resultatenset op de gekozen formaten. |
| callback | 0-1 | een callback string | Wordt gebruikt voor JavaScript implementaties. Het meegeven resulteert in een JSONP respons. |
Voorbeeld
- https://proxy.edurep.nl/v3/search?mode=json&query=fiets
- https://proxy.edurep.nl/v3/search?mode=json&query=fiets&x-term-drilldown=lom.classification.obk.educationallevel.id
- https://proxy.edurep.nl/v3/search?mode=json&query=fiets&technicalFormats=video&x-term-drilldown=lom.classification.obk.educationallevel.id
JSON Respons
Aangezien het antwoord geen standaard NL LOM is, wat extra uitleg over het uitvoerformaat. Dit bestaat uit een aantal onderdelen:
- config: De zoekopdracht zoals deze aan de endpoint werd meegegeven.
- api-version: De versie van de JSON endpoint.
- status: Toont of er tijdens het zoeken en maken van het antwoord problemen waren.
- caching: Toont caching informatie.
- search: De gevonden individuele resultaten.
- drilldowns: Drilldown informatie over de resultaatset.
- navigation: Informatie voor het ophalen van de volgende "pagina" in de resultaatset.
|
|
Alleen de inhoud van search, drilldowns en navigation staat vast. Over de inhoud van de andere velden wordt geen garantie gegeven. |
Search
Het "search" deel bevat algemene informatie over de zoekopdracht en een "records" deel waarin de metadata van elk record te vinden is. De velden van elk record zijn gebaseerd op een slimme combinatie van NL LOM, de collectielijst en eigen inzicht.
Zo is alle afbeeldingsinformatie (thumbnails, mimetype icon) gegroepeerd, net zoals informatie over collecties (identifier, naam, toegangsrechten). Vocabulairevelden bevatten een "value", een identifier waarde, maar ook een "human", die een waarde bevat voor menselijke interfaces.
schema
Er is een JSON Schema beschikbaar op GitHub. Dit schema geeft vooralsnog alleen een definitie van een record in een searchresult.
overzicht
In de volgende tabel staat een overzicht van de waarden in een record.
| naam | #### | type | omschrijving |
|---|---|---|---|
| title | 1 | string | titel |
| description | 1 | string | omschrijving |
| keyword | 0-* | array | trefwoord(en), per entry één trefwoord. |
| language | 1-* | string | de gebruikte talen in de bron, conform ISO 639-1 of "x-none" |
| aggregationlevel | 1 | string | het aggregatieniveau van de bron. Toegestane waarden "1", "2", "3" of "4". |
| publisher/name | 0-* | string | de uitgever(s) van de bron |
| publisher/datetime | 1 | string | de laatste bekende publicatiedatum, conform ISO 8601 ("2009-10-22T05:23:12") |
| publisher/timestamp | 1 | integer | de laatste bekende publicatiedatum, conform Unix time (bijv. 1256181792) |
| author/name | 0-* | string | de auteur(s) van de bron |
| author/datetime | 1 | string | de laatste bekende auteursdatum, conform ISO 8601 ("2009-10-22T05:23:12") |
| author/timestamp | 1 | integer | de laatste bekende auteursdatum, conform Unix time (bijv. 1256181792) |
| format/mimetype | 1 | string | bestandsformaat van bron, conform IANA mimetype of non-digital in geval van een fysiek product zoals een papieren boek. |
| format/mapped_format | 1 | string | identifier van het gemapte technische formaat |
| format/mapped_format_name | 1 | string | naam van het gemapte technische formaat |
| format/mapped_format_specific | 1 | string | naam van het specifieke gemapte technische formaat |
| learningresourcetype/human | 1 | string | Deze learningresourcetype is geen exacte vertaling van de waarde die in NL-LOM wordt aangeleverd. De waarde is daarin afhankelijk van het aggregationlevel veld. Indien deze waarde 1 of 2 is, dan wordt de bovenste waarde voor learningresourcetype in NL-LOM in dit veld overgenomen. Indien de waarde gelijk is aan 3, is deze waarde "Les", en indien de waarde gelijk is aan 4, is deze waarde "Serie lessen". |
| learningresourcetype/value | 1 | array | Een opsomming van de learningresourcetype waarden uit het oorspronkelijke record conform NL-LOM. |
| intendedenduserrole | 0-* | array | mogelijke waarden voor intendedenduserrole |
| intendedenduserrole/human | 1 | string | presentatie waarde voor intendedenduserrole |
| intendedenduserrole/value | 1 | string | oorspronkelijke waarde voor intendedenduserrole uit het oorspronkelijke record conform NL-LOM. |
| context | 0-* | string | educatieve sectoren waarin de bron toepasbaar is |
| typicalagerange | 1 | string | leeftijdsgroep waarvoor de bron toepasbaar is |
| cost/human | 1 | string | De presentatie waarde of de bron geld kost. |
| cost/value | 1 | string | De oorspronkelijke waarde uit NL-LOM. |
| copyright/human | 1 | string | De copyright vermelding zoals door de bron is aangeleverd. |
| copyright/value | 1 | string | De identifier van de copyright vermelding (of yes,no) |
| discipline/<uuid> | 0-* | string | Een lijst van OBK inhouden (vakgebieden), zie ook het voorbeeld. |
| educationallevel/<uuid> | 0-* | string | Een lijst van OBK leerniveaus, zie ook het voorbeeld. |
| educationalobjective/<uuid> | 0-* | string | Een lijst van OBK leerdoelen, zie ook het voorbeeld. |
| time/seconds | 1 | integer | De aggregatie van het duration (afspeelduur) en het typicallearningtime (studielast) veld, waarbij typicallearningtime voorkeur geniet. De waarde is -1 als er geen waarde bekend is of niet van toepassing. |
| time/human | 1 | string | De time/seconds waarde uitgeschreven in menselijke presentabele tekst. |
| time/typicallearningtime | 1 | integer | studielast in seconden, -1 indien de waarde niet is opgegeven of niet van toepassing. |
| time/duration | 1 | integer | afspeelduur in seconden, indien -1 dan is er geen waarde opgegeven. Voorkeur is |
| repository/id | 1 | string | De Edurep identifier van de bron repository van het record. |
| repository/name | 1 | string | De naam van de bron repository van het record. |
| repository/accessrights/human | 1 | string | De menselijke tekst representatie voor de toegankelijkheid van de bron. |
| repository/accessrights/value | 1 | string | De identifier voor de toegankelijkheid van de bron. Deze informatie is afkomsting uit de collectielijst. |
| image/mimetype_icon | 1 | string | Een url naar een pictogram representatief voor het mimetype van de bron. |
| image/icon | 0-1 | string | Een url naar een door de record aanbieder bepaald pictogram voor de bron. |
| image/thumbnail | 0-1 | string | Een url naar een kleinere versie van de bron (afbeeldingsthumbnail of video still). |
| image/previewimage | 0-1 | string | Een aggregatie van thumbnail en icon. Als een van beide aanwezig is, staat deze ook in previewimage. |
| identifier/recordidentifier | 1 | string | De identifier van het metadatarecord in Edurep. |
| url/location | 0-1 | string | De url waar de bron te vinden is, indien de bron via het internet toegankelijk is. |
| url/embed | 0-1 | string | De embed-url van de bron waarmee de bron ge-embed kan worden in een andere pagina. |
| url/landingpage | 0-1 | string | Een landingpage link duidt op een pagina die niet de resource is, maar wel naar de resource linkt (de location link) wijst direct naar de resource. |
| social/nrofreviews | 1 | integer | Het aantal reviews bij deze bron. |
| social/nrofratings | 1 | integer | Het aantal ratings bij deze bron. |
| social/nroftags | 1 | integer | Het aantal tags bij deze bron. |
| social/rating | 1 | number | De genormaliseerde gemiddelde rating bij deze bron. Zie ook Edurep's geaggregeerde sociale metadata. |
copyright
De value voor copyright kan een aantal waarden aannemen, yes, no, en een set Creative Commons identifiers. Er is altijd een corresponderende human waarde voor het aangegeven copyright type.
"copyright": {
"value": "yes",
"human": "For information on the use of archive material, please contact the Customer Service department of the Netherlands Institute for Sound and Vision: klantenservice@beeldengeluid.nl."
}
OBK
De secties discipline, educationallevel en educationalobjective bevatten informatie over vakgebied, leerniveau en leerdoel. De uuid identifiers zijn afkomsting uit het Onderwijs BegrippenKader.
"educationallevel": {
"512e4729-03a4-43a2-95ba-758071d1b725": "Primair onderwijs",
"2a1401e9-c223-493b-9b86-78f6993b1a8d": "Voortgezet onderwijs",
"caa97efc-a713-41ea-a845-1534ca65eac9": "Beroepsonderwijs en Volwasseneneducatie"
}
time
De time sectie bevat de aggregatie van het duration (afspeelduur) en het typicallearningtime (studielast) veld, waarbij typicallearningtime voorkeur geniet. De waarde staat gerepresenteerd in seconden en in menselijke tekst,
"time": {
"seconds": 951,
"human": "16 minuten"
}
repository
De repostory sectie bevat informatie over de bron repository. De Edurep identifier staat aangegeven, alsmede de naam en de toegangsrechten. Deze informatie is afkomsting uit de collectielijst, daar staat ook de waardenset van de accessrights value.
"repository": {
"id": "nationaalarchief",
"name": "Nationaal Archief Beeldbank",
"accessrights": {
"human": "Openbaar",
"value": "public"
}
}
Drilldowns
De drilldowns worden per meegegeven veld teruggegeven net zoals in de reguliere respons. Alleen de vak en leerniveau drilldowns hebben een iets andere eigenschap, namelijk dat ze in boomvorm worden teruggegeven in plaats van als platte lijst. Het gaat daarmee specifiek over de volgende velden:
- lom.classification.obk.discipline.id
- lom.classification.obk.educationallevel.id
Bijvoorbeeld:
"lom.classification.obk.educationallevel.id": [
{
"identifier": "15d693b8-fbe1-4112-8135-4a20aba5101c",
"caption": "Voor- en vroegschoolse educatie",
"alternative": null,
"records": 392,
"purpose": "educationallevel",
"parent": null,
"children": [ ]
},
{
"identifier": "512e4729-03a4-43a2-95ba-758071d1b725",
"caption": "Primair onderwijs",
"alternative": null,
"records": 58730,
"purpose": "educationallevel",
"parent": null,
"children": [
{
"identifier": "82ca4442-246c-44b3-a562-7b101793feb4",
"caption": "PO groep 1",
"alternative": null,
"records": 6517,
"purpose": "educationallevel",
"parent": "512e4729-03a4-43a2-95ba-758071d1b725",
"children": [ ]
},
{
"identifier": "c007e4dd-a3d4-4f33-902d-778e3bbeeddb",
"caption": "PO groep 2",
"alternative": null,
"records": 6713,
"purpose": "educationallevel",
"parent": "512e4729-03a4-43a2-95ba-758071d1b725",
"children": [ ]
}
]
}
]
Technisch Formaat
De Widget proxy maakt een speciale mapping voor mimetypes zodat de veelheid aan mimetypes geaggregeerd worden naar een beperkte set logische technische formaten:
- image: Afbeelding,
- video: Video
- audio: Audio
- spreadsheet: Spreadsheet
- presentation: Presentatie
- text: Tekst
- wikiwijsarrangement: Wikiwijs Arrangement
- pdf: PDF
- digiboard: Digiboard
- app: App
- archive: Archief
- message: Bericht
- ebook: eBook
- googleearth: Google Earth
De losse mimetypes zijn als volgt gemapt naar de technische formaten.
| mime type | technisch formaat | naam |
|---|---|---|
| application/x-yossymemo | digiboard | Hitachi StarBoard |
| application/x-ibooks+zip | ebook | iBook |
| image/bmp | image | Bitmap |
| application/vnd.openxmlformats-officedocument.presentationml.pre | presentation | Office Open Presentatie bestand |
| application/vnd.openxmlformats-officedocument.presentationml.sli | presentation | Office Open Diavoorstelling bestand |
| application/vnd.oasis.opendocument.spreadsheet | spreadsheet | OpenDocument Spreadsheet |
| application/postscript | text | PostScript |
| application/vnd.ms-word | text | Microsoft Word Document |
| application/x-tar | archive | TAR archief |
| application/vnd.ms-word.document.macroEnabled.12 | text | Office Open XML |
| application/x-stuffit | archive | StuffIt Archief |
| application/x-koan | audio | Koan Audio |
| application/vnd.koan | audio | Koan Audio |
| audio/midi | audio | MIDI |
| application/vnd.openxmlformats-officedocument.wordprocessingml.template | text | Office Open XML |
| image/pjpeg | image | JPEG |
| text/rtf | text | Rich Text Format |
| application/Inspire | digiboard | Promethean ActivInspire bestand |
| message/rfc822 | message | |
| video/quicktime | video | Quicktime Video |
| application/x-AS3PE | digiboard | Promethean ActivStudio |
| application/vnd.ms-publisher | text | Office Publisher Document |
| application/vnd.google-earth.kmz | googleearth | Google Earth KMZ |
| image/png | image | PNG |
| video/x-msvideo | video | AVI |
| application/ppt | presentation | Office Powerpoint |
| application/x-rar-compressed | archive | RAR Archief |
| application/rtf | text | Rich Text Format |
| application/vnd.openxmlformats-officedocument.spreadsheetml.sheet | spreadsheet | Office Open Spreadsheet bestand |
| video/mpeg | video | MPEG |
| image/x-icon | image | Icoon |
| image/x-ms-bmp | image | Bitmap afbeelding |
| application/x-pdf | ||
| image/tiff | image | TIFF afbeelding |
| application/vnd.openxmlformats-officedocument.presentationml.slideshow | presentation | Office Open Diavoorstelling bestand |
| application/x-java | app | Java Applet |
| image/jpg | image | JPG |
| application/x-Inspire | digiboard | Promethean ActivInspire bestand |
| application/x-smarttech-notebook | digiboard | SMART Notebook |
| application/x-zip-compressed | digiboard | Heutink HD Board |
| application/x-ACTIVprimary3 | digiboard | Promethean ActivPrimary |
| application/vnd.ms-excel | spreadsheet | Microsoft Excel bestand |
| text/plain | text | Tekst bestand |
| audio/x-wav | audio | WAV bestand |
| application/vnd.openxmlformats-officedocument.presentationml.presentation | presentation | Office Open Presentatie bestand |
| application/x-mplayer2 | video | Web Video |
| image/gif | image | GIF afbeelding |
| audio/mpeg | audio | MP3 audio |
| application/vnd.openxmlformats-officedocument.wordprocessingml.document | text | Office Open Tekstverwerking bestand |
| video/mp4 | video | MP4 video |
| application/vnd.ms-powerpoint | presentation | Microsoft Powerpoint bestand |
| video/x-ms-wmv | video | Windows Media Video |
| video/x-flv | video | Flash video |
| text/xml | text | XML bestand |
| application/msword | text | Microsoft Word Document |
| application/zip | archive | ZIP archief |
| video/x-ms-asf | video | ASF video |
| application/pdf | ||
| text/html | text | HTML pagina |
| image/jpeg | image | JPEG afbeelding |
| application/x-Wikiwijs-Arrangement | wikiwijsarrangement | Wikiwijs Arrangement |
JSON Simple Respons
Dit is een versimpelde variant van de JSON respons en aan te roepen met mode "simplejson". Dit formaat bevat alleen title, description en url. Bijvoorbeeld:
{
"title": "Frame (fiets)",
"description": "Een frame is het dragende gedeelte (chassis) van een fiets, bromfiets of motorfiets. Het wordt ook wel rijwielgedeelte of kader genoemd.",
"url": "http://nl.wikipedia.org/wiki/Frame_(fiets)"
}
RSS Respons
Dit is een rss respons van de zoekopdracht en aan te roepen met mode "rss". Het formaat bevat net als de versimpelde json alleen title, description en url. Bijvoorbeeld:
<?xml version="1.0" encoding="utf-8"?>
<rss xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0">
<channel>
<title>Kennisnet zoekopdracht</title>
<link>http://proxy.edurep.nl/v2/search?mode=rss&query=fiets</link>
<atom:link href="http://proxy.edurep.nl/v2/search?mode=rss&query=fiets" rel="self" type="application/rss+xml" />
<description>Deze feed is afkomstig van Edurep, de zoekmachine voor lesmateriaal. Meer info is te vinden op: http://kn.nu/edurep-widget</description>
<item>
<title><![CDATA[Frame (fiets)]]></title>
<link><![CDATA[http://nl.wikipedia.org/wiki/Frame_(fiets)]]></link>
<description><![CDATA[Een frame is het dragende gedeelte (chassis) van een fiets, bromfiets of motorfiets. Het wordt ook wel rijwielgedeelte of kader genoemd.]]></description>
<guid><![CDATA[http://nl.wikipedia.org/wiki/Elektrische_fiets]]></guid>
</item>
</channel>
</rss>