Metoder

Version 1.1 (uppdaterad 2013-12-05)

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

Exempel:
http://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 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:
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

Denna metod ger ett svar med information för enskilda län, kommun, landskap och socken. För socken och landskap visas även yta (polygon, geografisk utsträckning).

Parametrar

uri (obligatorisk)
Denna parameter anger den persistenta URI:n för resursen.
Exempel:
Kommun: http://kulturarvsdata.se/ksamsok/api?method=getGeoResource&uri=http://kulturarvsdata.se/resurser/aukt/geo/municipality%230117&x-api=test
Socken: http://kulturarvsdata.se/ksamsok/api?method=getGeoResource&uri=http://kulturarvsdata.se/resurser/aukt/geo/parish%231&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


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:
http://www.kulturarvsdata.se/ksamsok/api?x-api=test&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:
http://www.kulturarvsdata.se/ksamsok/api?x-api=test&method=search&query=text=yxa&recordSchema=xml&fields=itemLabel,itemDescription,thumbnail,url
http://www.kulturarvsdata.se/ksamsok/api?x-api=test&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.