Version 1.1 (uppdaterad 2012-02-08)

Gemensamma parametrar

Nedanstående parametrar används av flera eller alla metoder.

Parametrar

query
Anger vad som skall sökas på. Systemet använder CQL-syntax för frågorna.

Exempel: query=item=”sten yxa” AND place=gotland NOT itemMaterial=brons

index
Denna parameter tar emot vilka index som metoden skall utföras på. Det finns ingen gräns för hur många index som kan skickas in, dock kan många index eller index med många unika värden leda till att denna metod blir prestandakrävande och långsam.

Exempel: index=mediaType=*|itemName=yxa*

stylesheet (frivillig)
Anger om någon stilmall (XSLT stylesheet) skall användas för att visa sökresultatet. Se exemplen nedan för respektive metod för att få rätt mall. De olika mallarna är nämligen anpassade för de olika API-metoderna.

Exempel: stylesheet=stylesheet/searchStyle.xsl

removeBelow (frivillig)
Kombinationer av unika värden som har antal relaterade poster under angivet värde tas bort ur svars-XML.

Exempel: removeBelow=3

x-api (obligatorisk)
Anger vilken API-nyckel som ska användas. Om man inte har en API-nyckel så fungerar värdet ”test” i avvaktan på att man får en nyckel. Nycklar används för att kunna följa upp statistik i K-samsök men kan även användas för att förhindra DoS-attacker vid behov.

Exempel: x-api=test

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 500. Denna sätts till 50 om inget annat anges eller om ett värde under 1 eller över 500 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:

www.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&x-api=test

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:

www.kulturarvsdata.se/ksamsok/api?method=statistic&stylesheet=stylesheet/statistic.xsl&index=mediaType=*|itemName=yxa*&removeBelow=3&x-api=test

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.

www.kulturarvsdata.se/ksamsok/api?method=statisticSearch&stylesheet=stylesheet/statistic.xsl&index=serviceOrganization=*&query=itemLabel>talk and itemLabel<talm&removeBelow=1&x-api=test

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:

www.kulturarvsdata.se/ksamsok/api?method=allIndexUniqueValueCount&stylesheet=stylesheet/allIndexUniqueValueCount.xsl&query=yxa&index=itemType|provinceName|serviceOrganization|thumbnailExists&x-api=test

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:

www.kulturarvsdata.se/ksamsok/api?method=facet&&stylesheet=stylesheet/facet.xsl&index=countyName|thumbnailExists&query=hus&removeBelow=1&x-api=test

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 ätts den till 3 som standard.
Exempel: maxValueCount=5

Exempel

www.kulturarvsdata.se/ksamsok/api?method=searchHelp&stylesheet=stylesheet/searchHelp.xsl&index=itemMotiveWord|itemKeyWord&prefix=sto*&maxValueCount=5&x-api=test

rss

Som namnet antyder så returnerar denna metod en RSS-feed 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

http://www.kulturarvsdata.se/ksamsok/api?method=getServiceOrganization&value=all&x-api=test

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.

uri (obligatorisk)
Den persistenta URI:n för objektet.

maxCount (frivillig)
Maximalt antal returnerade relationer.

Exempel

http://kulturarvsdata.se/ksamsok/api?method=getRelations&relation=all&objectId=raa/fmi/10028201230001&maxCount=1000&x-api=test

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
http://kulturarvsdata.se/ksamsok/api?method=getRelationTypes&relation=all&x-api=test

getGeoResource

Den här metoden är inte riktigt klar. Med den kommer man att kunna få fram information och polygon för socken, landskap, kommun eller län. Detta är en del i vår strävan att uppfylla kraven som geografisk auktoritet, inte bara mot K-samsök utan även mot andra aktörer.

Parametrar

uri (obligatorisk)
Denna parameter anger den persistenta URI:n för resursen.

Exempel:

http://kulturarvsdata.se/ksamsok/api?method=getGeoResource&uri=http://kulturarvsdata.se/resurser/aukt/geo/municipality%230117&x-api=test

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:

http://www.kulturarvsdata.se/ksamsok/api?method=stem&words=kappe&x-api=test