Metoder

Dokumentation om de olika metoderna i K-samsöks API.

Kommande ändringar på K-samsöks API och protokoll utlysas här.

search

Metoden search utför en sökning efter objekt i systemet K-samsök.
Resultatet av metoden är ett XML-svar innehållande x antal ”records” med information om objekten som träffats.

Parametrar

query (obligatorisk)
hitsPerPage (frivillig)
Anger hur många träffar som skall visas per sida, eller rättare sagt hur många träffar som det max skall finnas i XML-svaret. Parametern tar ett numeriskt värde mellan 1 till 1 000. Denna sätts till 50 om inget annat anges eller om ett värde under 1 eller över 1 000 anges.
Exempel: hitsPerPage=12
startRecord (frivillig)
Anger vart någonstans sökning skall börja i resultatet. Som default hämtas posterna 1-50. Anger man istället startRecord=11 så hämtas istället posterna 11-60.
Exempel: startRecord=50
stylesheet (frivillig)
sort (frivillig)
Anger att resultatet skall sorteras efter givet index.
Exempel: sort=itemType
sortConfig (frivillig)
Anger om resultatet skall sorteras stigande (ascending) eller avtagande (descending). Default är stigande. Möjliga värden är: asc och desc
Exempel: sortConfig=desc
recordSchema (frivillig)
Anger vilket record-schema som skall användas. I dagsläget finns endast ett som heter presentation. För att använda detta skriver man recordSchema=presentation Resultatet av detta blir att enbart presentationsdata returneras. Om inget record-schema anges returneras all data för objekten.
Exempel: recordSchema=presentation

Exempel: En sökning med metoden search kan se ut på följande sätt:
https://kulturarvsdata.se/ksamsok/api?method=search&stylesheet=stylesheet/searchStyle.xsl&query=item=yxa&place=gotland&startRecord=10&hitsPerPage=25&sort=itemName&sortConfig=asc&recordSchema=presentation

Fler exempel: metoden search

statistic

Denna metod returnerar en lista över alla kombinationer av alla unika värden för givna index och antal poster som matchar dessa värden.

Parametrar

index (obligatorisk)
stylesheet (frivillig)
removeBelow (frivillig)

Exempel: En sökning med metoden statistic kan se ut på följande sätt:
https://kulturarvsdata.se/ksamsok/api?method=statistic&stylesheet=stylesheet/statistic.xsl&index=mediaType=*&removeBelow=3

statisticSearch

Denna metod fungerar i princip som statistic bortsett från att den gör det möjligt att filtrera resultatet med ett query. Med andra ord funkar denna metod som en kombination av search och statistic (där av namnet statisticSearch).

Parametrar

index (obligatorisk)
stylesheet (frivillig)
query (obligatorisk)
removeBelow (frivillig)

Exempel: Ett anrop till metoden statisticSearch kan se ut på följande sätt
https://kulturarvsdata.se/ksamsok/api?method=statisticSearch&stylesheet=stylesheet/statistic.xsl&index=serviceOrganization=*&query=itemLabel>talk and itemLabel<talm&removeBelow=1

allIndexUniqueValueCount

Returnerar en lista över relevanta index och antalet unika värden dessa index har som matchar given fråga.

Parametrar

query (obligatorisk)
index (frivillig)
stylesheet (frivillig)

Exempel: En sökning med allIndexUniqueValueCount kan se ut på följande sätt:
https://kulturarvsdata.se/ksamsok/api?method=allIndexUniqueValueCount&stylesheet=stylesheet/allIndexUniqueValueCount.xsl&query=yxa&index=itemType

facet

Metoden utför en facettsökning för givna index med given fråga som filter.

Parametrar

index (obligatorisk)
query (obligatorisk)
stylesheet (frivillig)
removeBelow (frivillig)

Exempel: En sökning kan se ut med metoden facet kan se ut på följande sätt:
https://kulturarvsdata.se/ksamsok/api?method=facet&&stylesheet=stylesheet/facet.xsl&index=countyName&query=hus&removeBelow=1

searchHelp

Denna metod är utvecklad för att göra det möjligt att få auto-text när en sökning skrivs. Alltså att ett system kan ge förlag på vad som skall skrivas utefter ett prefix.

Parametrar

index (obligatorisk)
prefix (frivillig)
Specificerar det prefix som skall användas vid sökningen. Om denna ej anges kommer prefixet automatiskt sättas till *. Om ett prefix skickas in utan en * på slutet kommer denna att läggas till automatiskt. Alltså sto blir sto*.
Exempel: prefix=sto*
stylesheet (frivillig)
maxValueCount (frivillig)
Anger hur många förslag man vill ha tillbaka från varje index. Om denna sätts till exempelvis 5 kommer man att få 5 förslag för varje index som skickas in (förutsatt att det finns 5 förslag, annars kommer färre ges) Anges inte denna sätts den till 5 som standard.
Exempel: maxValueCount=5

Exempel:
https://kulturarvsdata.se/ksamsok/api?method=searchHelp&stylesheet=stylesheet/searchHelp.xsl&index=itemMotiveWord&prefix=sto*&maxValueCount=5

rss

Som namnet antyder så returnerar denna metod ett RSS-flöde från K-samsök, eller rättare sagt en mediaRSS-feed. I stort sett fungerar metoden precis som metoden search bortsett från att istället för ett svar i XML-format får man ett svar i mediaRSS-format.

Parametrar

Se parameterbeskrivningen för metoden search då dessa två metoder har identiska parametrar.

getServiceOrganization

Denna metod skiljer sig från de övriga då den tekniskt sett inte söker i K-samsök. Istället så returneras information om de institutioner som K-samsök hämtar data ifrån. Informationen om institutionerna anges själv av varje institution och inte av Riksantikvarieämbetet (bortsett från de databaser som tillhör Riksantikvarieämbetet förstås).

Parametrar

value (obligatorisk)
Denna parameter anger vilken institution man vill hämta information om. Anger man exempelvis value=raä så hämtas information om Riksantikvarieämbetet. Om man inte vet vad de olika institutionerna har för förkortningar eller bara vill ha information om alla institutioner så kan man skriva value=all vilket returnerar information om samtliga institutioner.

Exempel:
https://kulturarvsdata.se/ksamsok/api?method=getServiceOrganization&value=all

getRelations

Metoden getRelations kan användas för att lista alla eller vissa relationer för ett objekt. Det är inte bara relationerna i det egna RDF-datat som hämtas, utan även relationer till det aktuella objektet från andra objekt. Det här innebär att det alltid räcker med enkelriktade relationer i K-samsök – man kan alltid hitta dem från båda håll.

Parametrar

relation (obligatorisk)
Med den här parametern anger du vilken relationstyp du vill lista. Om du vill se alla relationstyper så anger du "all". I det resulterande svaret kan vissa relationer ha attributet source="deduced", vilket är en markering att relationen har hittats hos det motstående objektet, inte hos det objekt du utgår från.
objectId (obligatorisk)
Den persistenta URI:n för objektet.
maxCount (frivillig)
Maximalt antal returnerade relationer.

Exempel:
https://kulturarvsdata.se/ksamsok/api?method=getRelations&relation=all&objectId=raa/fmi/10028201230001&maxCount=1000

getRelationTypes

Visar relationer som ett objekts context kan ha till ett annat objekt. Metoden retunerar namn med dess invers(reverse) samt svenska titeln.

Parametrar

relation (obligatorisk)
Med den här parametern anger du vilken relationstyp du vill lista. Om du vill se alla relationstyper så anger du "all".

Exempel:
https://kulturarvsdata.se/ksamsok/api?method=getRelationTypes&relation=all

stem

Det här är en enkel metod för att se hur K-samsök hanterar ordstamning (böjningsformer). Man får tillbaka ordens stammar.

Parametrar

words (obligatorisk)
Denna parameter anger vilket eller vilka ord du vill kontrollera böjningsformer för. Konstigheter kan åtgärdas om de meddelas till K-samsöksteamet.

Exempel:
https://kulturarvsdata.se/ksamsok/api?method=stem&words=kappe

recordschema

Anger vilket record-schema som skall användas för söksvaret, dvs vilket
(XML-)format svarsposterna ska ha. Man kan antingen begära en posts hela
RDF, dess presentationsdata eller valfria fält. Default är att postens RDF returneras om parametern utelämnas.
Möjliga värden är:

  • rdf
  • presentation
  • xml

Exempel:
https://kulturarvsdata.se/ksamsok/api?method=search&query=geoDataExists=j&recordSchema=xml&fields=itemDescription,itemLabel,lon,lat

Parametrar

fields (obligatorisk om recordSchema=xml, annars oanvänd; se ovan)
Anger vilka fält du önskar i svaret. Nästan alla index man kan söka på kan anges här i en kommaseparerad lista. Utöver dem även vissa extrafält som tex thumbnail för att få en posts tumnagel. Fältet itemId läggs också alltid till i svaret även om den inte finns angiven.
Möjliga värden är:

  • kommaseparerad lista av nästan alla sökbara index
    samt:

    • thumbnail
    • url
    • lon (longitud)
    • lat (latitud)

Exempel:
https://kulturarvsdata.se/ksamsok/api?method=search&query=text=yxa&recordSchema=xml&fields=itemLabel,itemDescription,thumbnail,url
https://kulturarvsdata.se/ksamsok/api?method=search&query=geoDataExists=j&recordSchema=xml&fields=itemLabel,itemDescription,lon,lat

JSON-LD

Om man vill ett objekt beskrivet som JSON-LD så kan man göra på två sätt:

  1. Man anger JSON-LD i sökvägen i URI:n innan objekts id, t.ex: http://kulturarvsdata.se/shm/object/jsonld/970897
  2. Man anger endast application/json, application/json-ld eller application/ld-json som Accept format i http-headern, samt anger inget format i URI:ns path, dvs: http://kulturarvsdata.se/shm/object/970897

Om man vill att svaret på api anrop ska vara i JSON så anger man application/json som Accept format i http-headern. Om api-anropets svar innehåller en eller flera RDF tripletter så kommer de vara serialiserade som JSON-LD.