Edurep:Jsonsearch: verschil tussen versies

Versie van 3 nov 2021 22:34

Met het jsonsearch endpoint worden Edurep responses in JSON format geleverd.

Endpoints

productie: https://wszoeken.edurep.kennisnet.nl/jsonsearch
staging: https://staging.edurep.kennisnet.nl/jsonsearch

Request

argument	#	omschrijving
query	1	CQL zoekopdracht
page-size	0-1	aantal resultaten per pagina, max 100
page	0-1	pagina van resultatenset
facet	0-*	veld om drilldown op uit te voeren
recordSchema	0-1	specificeer recordSchema (default jsonld)

Query

In Edurep kan er worden gezocht op AND/OR/NOT combinaties van trefwoorden, binnen de totale set of binnen specifieke velden.

fiets AND pomp
kasteel AND (ridder OR ridders)
vis AND walvis NOT potvis
breuken AND vak=wiskunde
breuken AND (titel=werkblad OR titel=taak)

Afhankelijk van de gebruikte zoekinterface zijn er verschillende zoekvelden beschikbaar, bekijk de veldenlijst voor een overzicht.

Voorbeelden:

/edurep/sruns: query=fiets AND pomp

/smo/sruns: query=smo.hReview.info exact "http://wikiwijs.samendelen.nl/get/smpid:5585/DS1"

Catalogus Service: query=Title=techniek AND Price<500

/jsonsearch: query=fiets AND schema:name="werkblad"

Beperkingen:

De waarde van het query argument mag maximaal 4096 tekens zijn, na urldecoding.
De zoekwoorden kunnen alleen letters en cijfers bevatten. Vanwege het indexatieproces zijn speciale karakters als # en $ zijn niet doorzoekbaar.
Wildcard zoeken is beperkt mogelijk. Zoeken op fiets* is wel mogelijk maar *fiets niet. De fiets* is mogelijk met minimaal 2 karakters. Het zoeken met het wildcard teken in een string (infix) is ook mogelijk, ook met minimaal 2 voorloopkarakters. Er mag maximaal 1 * voorkomen per trefwoord.

Paginering

Edurep resultaten worden gepagineerd aangeboden. Standaard worden de eerste 10 teruggegeven, en het is met parameters mogelijk om de verschillende pagina's van de totale resultatenset op te halen (tot een maximum van 4000). Bij een startRecord hoger, wordt een foutmelding meegegeven, maar wordt de laatste pagina getoond (alsof de startRecord gelijk is aan 4000).

Paginering in jsonsearch werkt via de volgende argumenten:

page
page-size

Met page-size kan het aantal resultaten per pagina worden ingesteld, en met page wordt aangegeven welke pagina van de totale resultatenset wordt teruggegeven.

/jsonsearch: query=*&page-size=20&page=2

Drilldown

Met een optionele term drilldown worden alle waarden van een bepaald veld cumulatief geteld over alle zoekresultaten. Dit kan slechts op een beperkt aantal velden. Er kunnen meerdere term drilldowns gedaan worden per search request door de velden te scheiden met een komma.

Het gewenste aantal resultaten in de drilldown kan worden aangegeven door ":<nummer>" aan de drilldown term toe te voegen. Als je ":0" toevoegt worden alle drilldown resultaten getoond.

De volgorde van de termen met een gelijk aantal kan verschillen per zoekopdracht. De sortering komt namelijk voort uit hoe het drilldown algoritme werkt. Voor elementen met dezelfde waarde is geen volgorde gedefinieerd omdat dit efficiënter is en weinig toegevoegde waarde heeft.

Een drilldown kan in Jsonsearch met het facet argument worden meegegeven.

/jsonsearch: query=*&facet=schema:license

Sortering

Er zijn is Edurep verschillende velden waarop gesorteerd kan worden. Standaard wordt de sortering van de zoekmachine aangehouden, en dat is op de door de zoekmachine bepaalde relevantie. Per veld kan er ascending of descending gesorteerd worden.

In de jsonsearch worden sorteerbare velden met het sort argument meegegeven. De sorteringsrichting wordt als volgt opgegeven: 'veldnaam' voor oplopend, en '-veldnaam' voor aflopend. Meerdere sorteervelden kunnen met meerdere "sort" parameters worden opgegeven of met "," gescheiden.

Oplopend:

/jsonsearch: query=dinosaurus&sort=schema:datePublished

Aflopend:

/jsonsearch: query=dinosaurus&sort=-schema:datePublished

recordSchema

Nederlands

English

In Edurep bestaan verschillende representaties en perspectieven van een record. Deze worden opgevraagd middels een recordSchema argument.

Sommige recordSchema's representeren verschillende formaten van een stuk leermiddel-metadata,
andere beschrijven andere sets data die zijn gekoppeld aan een leermiddel-metadata record.
Afhankelijk van het gebruikte protocol zijn er verschillende opties beschikbaar.

Met de jsonsearch kan het recordSchema argument worden gebruikt om een ander recordSchema op te halen.

recordSchema	omschrijving
jsonld (default)	Record in Jsonld formaat
jsonld-plus	Record in Jsonld formaat plus gekoppelde reviews (max 10)

Response

veld	#	beschrijving
/response	1	response containter
/response/total	1	aantal records van totale respons
/response/items	0-1	lijst met response records
/response/facets	1	facets container
/response/facets/<facetid>	0-*	voor elke opgevraagde valide facet een container met de facet waarden
/response/facets/<facetid>/count	1	aantal keer dat facet waarde voorkomt in resultatenset
/response/facets/<facetid>/link	1	directe link naar query op facet waarde
/response/facets/<facetid>/link	1	de individuele facet waarde
/response/next	0-1	container met informatie over volgende pagina
/response/next/link	1	directe link naar volgende pagina
/response/next/page	1	nummer van volgende pagina
/response/previous	0-1	container met informatie over vorige pagina
/response/previous/link	1	directe link naar vorige pagina
/response/previous/page	1	nummer van vorige pagina
/response/querytimes	1	querytimes container
/request	1	request container
/request/query	1	gestelde query
/request/page-size	0-1	gevraagd aantal resultaten per pagina
/request/page	0-1	gevraagde paginanummer
/request/facet	0-1	container met opgevraagde facets
/request/facet/index	1	individuele gevraagde facet waarde
/request/facet/max-terms	1	opgevraagde maximum aantal waarden voor facet waarde
/version	1	api versie

voorbeeld

{
  "response": {
    "total": 763,
    "items": [
      {}, {}
    ],
    "facets": {
      "example:facet1": [
        {
          "count": 212,
          "link": "/jsonsearch?facet=schema%3Alicense&facet=dcterms%3Apublisher%3A40&facet-filter=example%facet1%3Dvalue1&page-size=1&query=fiets",
          "value": "value1"
        }
      ],
      "example:facet2": [
        {
          "count": 213,
          "link": "/jsonsearch?facet=schema%3Alicense&facet=dcterms%3Apublisher%3A40&facet-filter=example%3Afacet2%3DvalueX&page-size=1&query=fiets",
          "value": "valueX"
        }
      ]
    },
    "querytimes": {
      "handlingTime": 0.328,
      "indexTime": 0.015,
      "queryTime": 0.021
    },
    "next": {
        "link": "/jsonsearch?facet=example%3Afacet1&facet=example%3Afacet2%3A40&page=4&page-size=1&query=fiets",
        "page": 4
    },
    "previous": {
        "link": "/jsonsearch?facet=example%3Afacet1&facet=example%3Afacet2%3A40&page=2&page-size=1&query=fiets",
        "page": 2
    }
  },
  "request": {
    "facet": [
        {
            "index": "example:facet1",
            "max-terms": 1
        },
        {
            "index": "example:facet2",
            "max-terms": 1
        }
    ],
    "page-size": 1,
    "page": 3,
    "query": "fiets"
  },
  "version": "0.1.beta"
}

Foutmeldingen

Een foutmelding uit de jsonsearch is te herkennen aan de "error" key in de response.

Voorbeeld

{
    "error": {
        "message": "Missing required argument: 'query'",
        "type": "MissingArgument"
    },
    "version": "0.1.beta"
}

Foutcodes

type	omschrijving
MissingArgument	een vereist argument ontbreekt in het verzoek

Veldenlijst

algemeen

zoekveld	x-term-drilldown	sortKeys	<, <=, >=, >	exact
schema:name
schema:identifier				V

LearningResource

zoekveld	x-term-drilldown	sortKeys	<, <=, >=, >	exact
schema:inLanguage	V			V
schema:description
schema:keywords
dcterms:coverage
lom:structure
lom:aggregationLevel	V			V
schema:version
schema:creativeWorkStatus
dcterms:creator	V			V
schema:dateCreated		V	V
dcterms:publisher	V			V
schema:datePublished		V	V
dcterms:contributor	V			V
schema:encodingFormat	V			V
schema:url				V
schema:interactivityType
schema:learningResourceType.schema:termCode	V			V
schema:audience.schema:audienceType	V			V
schema:typicalAgeRange
lom:difficulty
schema:timeRequired.inSeconds			V
schema:isAccessibleForFree	V			V
schema:license	V			V
schema:copyrightNotice
schema:isBasedOn
schema:isPartOf
schema:hasPart
dcterms:isReferencedBy
dcterms:isVersionOf
schema:encoding.schema:encodingFormat
dcterms:accessRights	V			V
schema:educationalAlignment.schema:name
schema:educationalAlignment.schema:targetName	V			V
schema:educationalLevel.schema:name
schema:educationalLevel.schema:termCode	V			V
schema:teaches.schema:termCode	V			V
schema:aggregateRating.schema:reviewCount		V	V
schema:aggregateRating.schema:ratingCount		V	V
schema:aggregateRating.edurep:tagCount		V	V
schema:aggregateRating.schema:ratingValue		V	V
schema:aggregateRating.edurep:bayesianRanking		V	V

Event

zoekveld	x-term-drilldown	exact
schema:location.schema:name
schema:location.schema:address.schema:addressLocality	V	V
schema:location.schema:address.schema:addressRegion	V	V
schema:location.schema:latitude
schema:location.schema:longitude
schema:location.schema:geo
schema:organizer.schema:name
schema:organizer.schema:location.schema:address.schema:addressLocality	V	V
schema:organizer.schema:location.schema:address.schema:addressRegion	V	V

invalid