Kom igång med K-samsöks API!

På den här sidan hittar ni kod, tips, och exempel för att hjälpa er snabbt komma igång och börja använda K-samsöks API!

Fler exempel kan man även hitta här. Fullständig dokumentation för K-samsöks webb-API finns här. Kommande ändringar på K-samsöks API och protokoll utlysas här.

Objekt-URI:er vs. API-anrop

Objekt i K-samsök använder URI:er som beständiga identifierare. URI:erna är upplösbara, och svarar med data om objektet i RDF/XML-format: http://kulturarvsdata.se/raa/fmi/10240200820001 Till skillnad från sökningar på https://kulturarvsdata.se/ksamsok/api... osv, att avreferera en K-samsök-URI på kulturarvsdata.se använder inte K-samsöks API.

Svarsformat: XML & JSON, RDF/XML & JSON-LD

Om inget annat anges, K-samsöks URI:er svarar med RDF/XML, och API:et svarar med XML som har träffobjektens RDF/XML inbäddad. Ett smidigt alternativ är dock att få ut svar från K-samsök i JSON-format – specifikt JSON-LD, eftersom K-samsök indexerar länkade data (RDF). Ange application/json eller application/json-ld i anropets http-Accept-header för att få svar som JSON-LD. Detta funkar för såväl URI:er som API-anrop.
Anger man i recordSchema=xml som val i anropet och även anger värdena för de fields man vill ha med i svaret, kan man få tillbaka ren (dvs icke-RDF) XML; anger man dessutom application/json i http-Accept-header:n får man tillbaka vanlig JSON (dvs inte JSON-LD).

Enkel Sökning

För att göra en enkel textsökning efter strängen ”runsten” kan man anropa API:et med search-metoden och en lämplig query-sträng på text, såhär:
https://kulturarvsdata.se/ksamsok/api?method=search&version=1.1&hitsPerPage=500&query=text=runsten
(Obs. att i det här exemplet får vi bara de första 500 resultat; för att se nästa 500 på nästa ”sida” måste vi ange en startRecord: &startRecord=501.)

Vill man söka i specifika fält kan man ändra den generiska query=text=… till fältet man vill söka i, t.ex. query=item=yxa. En komplett lista på fälten man kan söka/filtrera i finns här. Det går att kombinera sökvillkoren med ”och”, ”eller”, ”inte” osv. enligt CQL-standarden: query=item="sten yxa" AND place=gotland NOT itemMaterial=brons.

Hitta bilder

För att hitta objekt (av valfri typ) som har ingående bilder kan man använda sig av parametern thumbnailExists (j/n):
https://kulturarvsdata.se/ksamsok/api?method=search&version=1.1&hitsPerPage=500&query=text=runsten%20AND%20thumbnailExists=j%20AND%20serviceName=kmb
För att hitta andra objekt som avbildar objektet i fråga måste man dock…

Hitta länkar mellan objekt

Det finns ofta länkar mellan objekt i K-samsök, framförallt mellan fysiska ting – lämningar, föremål osv. – och bilder som avbildar dem, böcker som beskriver dem osv. Det finns även andra sorters länkar t.ex. mellan personer och objekt de har ägt, händelser de var närvarande vid, osv. För att hitta sådana länkar använder man metoden getRelations tillsammans med sista delen av objektets URI som objectId:
https://kulturarvsdata.se/ksamsok/api?method=getRelations&version=1.1&relation=all&maxCount=1000&inferSameAs=yes&objectId=raa/fmi/10048200010001
Vill man begränsa sökningen till enbart en sorts länk, anger man det i parametern relation. I det här exemplet vill vi hitta andra objekt (antagligen bilder) som avbildar objektet i fråga:
https://kulturarvsdata.se/ksamsok/api?method=getRelations&version=1.1&relation=isVisualizedBy&maxCount=1000&inferSameAs=yes&objectId=raa/fmi/10048200010001

UGC-länkar

Vid sidan om K-samsök finns det även en UGC-hubb där användare kan bidra med sina egna länkar, framförallt genom Kringla. I UGC-hubben finns det flera länkar som kopplar ihop objekt inom K-samsök, men även länkar som kopplar K-samsöksobjekt med externa resurser. Här hittar du relationer till artiklar på Wikipedia, bilder på Wikimedia Commons, objekt i Europeana, och bibliografiska poster hos Kungliga bibliotekets Libris tjänst.

UGC-hubben har sitt eget API, som skiljer sig lite från K-samsöks. Så här söker man på UGC-länkar kopplat till ett objekt:
https://ugc.kulturarvsdata.se/UGC-hub/api?x-api=ex2147ap36&method=retrieve&scope=all&maxCount=25&objectUri=http://kulturarvsdata.se/raa/fmi/10240200820001
Svaren levereras per default i XML-format; om svar önskas i JSON-format, lägg till &format=json i query-strängen:
https://ugc.kulturarvsdata.se/UGC-hub/api?x-api=ex2147ap36&method=retrieve&scope=all&maxCount=25&format=json&objectUri=http://kulturarvsdata.se/raa/fmi/10240200820001

Sök inom ett geografiskt område

K-samsöks API stödjer geografiska sökningar med valfri koordinatsystem. Sökindexet boundingBox begränsar sökningen till en fyrkantig yta där två motstående hörn anges med koordinater. Konstanter finns för vissa vanliga koordinatsystem (RT90, SWEREF99, WGS84) och andra kan ange enligt EPSG:xxxx. Några exempel:
https://kulturarvsdata.se/ksamsok/api?&method=search&version=1.1&hitsPerPage=25&query=boundingBox=/WGS84%20%2212.883397%2055.56512%2013.01874%2055.635582%22
https://kulturarvsdata.se/ksamsok/api?method=search&version=1.1&hitsPerPage=25&query=boundingBox=/SWEREF99%20%22366524.557%206159714.112%20375281.959%206167302.335%22%20AND%20text=grav

Exempel

Här följer några exempelsökningar som ska visa hur sök-API:et funkar.

Hitta alla byggnadsminnen inom en kommun

Här söker vi efter alla objekt av itemTyp byggnad, som har text som beskriver dem som statliga- eller kyrkliga byggnads- eller kulturminnen, men som inte är hävda sådana, och som befinner sig i Tomelilla kommun, Skåne:
https://kulturarvsdata.se/ksamsok/api?method=search&version=1.1&hitsPerPage=500&query=text=%22statligt%20byggnadsminne%22%20OR%20%22statligt%20kulturminne%22%20OR%20%22kyrkligt%20byggnadsminne%22%20OR%20%22kyrkligt%20kulturminne%22%20NOT%20%22h%C3%A4vt%22%20AND%20itemType=byggnad%20AND%20municipality=1270
Obs. att vi har angivit Tomelilla kommun med sin kommunkod, 1270 på attributen municipality; om man inte kan hela landets samtliga kommunkoder utantill kan man alternativt ange kommunens namn med attributet municipalityName, men i så fall kan det vara bra att även specificera andra geografiska begränsningar som t.ex. län, för säkerhets skull. Vi skulle t.ex. kunna byta ut …AND%20municipality=1270 från exemplet ovan med …AND%20countyName=Sk%C3%A5ne%20AND%20municipalityName=Tomelilla.

Hur färskt är datat?

K-samsöksobjekt kan ha flera datumfält; alla använder formatet YYYY-MM-DD enligt ISO 8601. För att veta när ett objekt senaste uppdaterades ska man kolla i fältet lastChangedDate. Andra fält som kan vara relevanta är addedToIndexDate (när objektet senast skördades till K-samsök), createdDate (när objektposten först skapades), och buildDate (tid när objektinformationen genererades).

Exempel kod

Triviala exempel på hur man kan anropa API:et och tolka svaren finns på Bash och Perl här. Bash-exemplet, som använder XMLStarlet, är kort och enkelt nog att återges här i sin helhet:

#!/usr/bin/env bash

# Search K-samsök using XML tools:
function query() {
	echo "Enter search term:"
	read query
	echo "Number of results (max 500)?"
	read number
	curl -s -g "https://kulturarvsdata.se/ksamsok/api?method=search&version=1.1&hitsPerPage=$number&query=text=$query" \
		| xml sel -N pres="http://kulturarvsdata.se/presentation#" -N ns5="http://kulturarvsdata.se/ksamsok#" -N rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" --template --match "/result/records/record/rdf:RDF/rdf:Description/ns5:presentation/pres:item" --sort A:T:- "pres:organization" -v "concat(pres:organization,'            ',pres:id,'            ',pres:type,'            ',pres:entityUri)" --nl \
		| grep -v '^$' \
		| sed -E 's!/(object|media|fmi)/!/\1/html/!g'
}

query

Ramverk

Albin Larsson har skrivit ramverk för att interagera med K-samsök för Python och PHP. Han har även skapat ett lager ovanpå API:et som ger ett mer REST-liknande gränssnitt. Det finns även verktyg för att enkelt ladda hem poster från en sökfrågas träfflista, eller hela datamängder, och importera dem in i en triplestore som RDF.