API

KulturNav erbjuder ett api för att söka i det data som finns lagrat. Svaret ges i JSON-format.

Data

Information om en entitet returneras i en JSON-struktur. Utförlig dokumentation av strukturen ligger tyvärr än så länge i att göra-listan. Innehållet, fältnamn, kan överblickas i schemat.

Entiteter i KulturNavs API

Det finns tre huvudtyper av objekt i KulturNav:

  • Dataset. Poster förvaltas och lagras i dataset. Ett dataset är en kollektion av poster. En post förvaltas endast i ett dataset (men den kan visas i flera). Läs mer om dataset.

  • List. Subklass till dataset. Innehåller ett urval av poster eller dataset som samlas i användarnas egna listor/mappar. En post kan finnas i många listor/mappar. Läs mer om listor/mappar.

  • Enskilda poster av olika entitetstyper: som då kan vara aktörer (Agent), termer (Concept), namngivana objekt (NamedObject) tidsintervall (Time) och platser (Place) med subklasser. Strukturen framgår av schemat.

Läs mer om informationen i KulturNav.

Om tidsfält

Tidsinformation, t ex en tidpunkt i ett tidsintervall, returneras i form av en sträng med en precisionsangivelse.

Årtal, exempel 1999:

value: "1999-Y"  

År-månad, exempel december 1999:

value: "199912-M"  

År-månad-dag, exempel 31 december 1999:

value: "19991231-D"  

Osäkra datum anges med ett frågetecken efter tidsangivelsen (?), exempel 1999?:

value: "1999?-Y"  

Okänd tid anges med ett frågetecken (?):

value: "?"  

Pågående tid anges med ett utropstecken (!):

value: "!"  

Läs mer om okänd, osäker och pågående tid.

Använda API

Hämta objekt via id

Man kan hämta ett enstaka objekt genom anropet

/api/[uuid]  

där uuid är objektets uuid. Resultatet är ett JSON-objekt med objektets data.

Hämta dataset via id

Man kan hämta alla objekt i ett dataset genom anropet

 /api/list/[uuid]  

där uuid är datasetets uuid. Resultatet är en JSON-lista (array) med datasetets post först och därefter posterna i datasetet.

Hämta dataset med offset

Man kan hämta en datamängd med början från ett visst offset med anropet

/api/list/[uuid]/[offset]  

där uuid är datasetets uuid och offset är från vilken position i listan man vill hämta. Om man vill hämta från det femte objektet och framåt använder man offset 4.

Hämta delmängd av dataset

Man kan hämta en delmängd av ett dataset med anropet

 /api/list/[uuid]/[offset]/[max]  

där uuid är datasetets uuid, offset är från vilken position man vill hämta (se Hämta dataset via offset), och max är max antal objekt man vill hämta.

Hämta översikter

Man kan hämta en översikt över nyckelegenskaper från en post, lista, dataset eller sök:

/api/summary/<uuid för vanlig post>  

returnerar postens summary-JSON, OBS! även när det bara är en post får man en JSON-array.

/api/summary/<uuid för dataset>  

returnerar summary-JSON för datasetets innehåll, för paginering:

/api/summary/<uuid för dataset>/<offset>/<antal>  

sökresultat:

/api/summary/<sökvillkor>  

returnerar summary-JSON för sökresultatet, paginering på samma sätt som för dataset.

Söka data

Man kan söka efter objekt med anropet

 /api/search/[sökvillkor]  

Se Sökvillkor för en beskrivning av syntax för sökvillkor.

Resultatet är en JSON-lista (array) med objektens data. Som standard returnerar anropet de 20 första sökträffarna. Ändra antal och startposition på samma sätt som för Hämta delmängd av dataset)

OR-satser:

Sök med eller inom en specificerad egenskap:

/api/search/{egenskap}:{värde1} OR {värde2}  

exempelvis:

entityType:Agent%20OR%20NamedObject

Sök efter hela fraser

/api/search/{egenskap}:"{sökfras}"  

exempelvis

/api/search/text:"titeln hertig av"

Räkna sökträffar

Man kan räkna hur många objekt som uppfyller ett sökvillkor med anropet

 /api/count/[sökvillkor]  

Se Sökvillkor för en beskrivning av syntax för sökvillkor.

Resultatet är ett JSON-objekt:

{  
    "searchCrit": "[sökvillkor]",  
    "count": [antal träffar]  
}  

Sökvillkor

Sökvillkor har formen

[fältnamn]:[värde]  

flera villkor kan kombineras med , (komma) mellan

[fältnamn]:[värde],[fältnamn]:[värde],[fältnamn]:[värde]  

sökningen träffar då de objekt som uppfyller samtliga villkor (logiskt OCH).

För att ange att ett fält inte skall ha ett visst värde, ange ett ! (utropstecken) före värdet

[fältnamn]:![värde]  

För att ange att ett fält skall ha ett mindre eller större värde ange < (mindre än) eller > (större än) före värdet. Detta är främst aktuellt för datumsökning.

[fältnamn]:<[värde]  
[fältnamn]:>[värde]  

Fältnamnen vid sök kan sedan version 1.5 anges med eller utan en ändelse som anger värdetyp (styrt av fältnamnsnotationen i sökindexet) och eventuellt språk (för textegenskaper).

Utan värdetyp:

  • Referensvärden (uuid) anges med fältnamnet, t ex superconcept.license
  • Sant/falskt värde anges med fältnamnet, t ex Superconcept.isPlaceHolder
  • Strängvärden anges med fältnamnet, t ex entity.code
  • Textvärden anges med fältnamnet, t ex entity.name. Språk hanteras nu i en separat parameter, se nedan.
  • Datumvärden anges enbart fältnamnet, t ex dataset.contentUpdatedAt

Med värdetyp:

  • superconcept.license_r (referensvärde)
  • superconcept.isPlaceHolder_b (sant/falskt värde)
  • entity.code_s (strängvärde)
  • entity.name_no_t (textvärde, sök i språk norska)
  • dataset.contentUpdatedAt_dt (datumvärde, ange datum på formatet YYYYMMDD hhmmss-S)

Följande grunddata behöver ingen ändelse:

  • entityType (objekttyp, med undertyper så matchar t.ex. entityType:Actor både personer, organisationer, djur och namngivna föremål)
  • actualEntityType (objeckttyp, exakt matchning, t.ex. så matchar actualEntityType:Concept enbart termer, inte taxoner och stilar)
  • detailedType (kategori i form av en referens till ett typ-koncept)
  • createdAt (tidpunkt när objektet skapades, format som för datumfält)
  • updatedAt (tidpunkt när objektet senast uppdaterades, format som för datumfält)
  • savedAt (tidpunkt när objektet skapades eller senast uppdaterades, format som för datumfält)
  • createdBy (användarnamn på den som skapade objektet)
  • updatedBy (användarnamn på den som senaste uppdaterade objektet)

Språkhantering

Språk anges i version 1.5 med med query-parameter ?lang={språk-kod} eller genom header Accept-Language: {språk}.

Exempel parameter:

 ?lang=sv  

Exempel header:

 Accept-Language: sv  

Tidigare var språkhanteringen angiven på egenskapsnivå i samband med värdesuffix (se ovan).

OR-satser:

Sök med eller inom en specificerad egenskap:

 /api/search/{egenskap}:{värde1} OR {värde2}  

exempelvis:

 entityType:Agent%20OR%20NamedObject  

Exempel på sökvillkor

Sök efter personposter med licens CC-0:

/api/search/actualEntityType:Person,superconcept.license:c223fa3f-84eb-4c42-ac63-e544ebf4c609  

Sök efter poster i datasetet "Arkitekter verksamma i Sverige" som skapats eller uppdaterats efter första april 2014:

/api/search/entity.dataset:2b7670e1-b44e-4064-817d-27834b03067c,savedAt:>20140401 000000-S  

Sök efter poster i datasetet "Arkitekter verksamma i Sverige" som har Samma som-referenser till objekt i Wikidata:

/api/search/entity.dataset:2b7670e1-b44e-4064-817d-27834b03067c,entity.sameAs:https%3A%2F%2Fwww.wikidata.org%2Fentity%2FQ*  

Sök efter personer med efternamnet Aagaard i datasetet "Fotografregisteret (Norge)":

/api/search/entityType:Person,entity.dataset:508197af-6e36-4e4f-927c-79f8f63654b2,person.lastName:Aagaard  

API-version

Returnerar senaste version av API som används default.

/api/version  

Åtkomst till posters versionshistorik

Visar en lista med postens revisionshistorik med den senaste posten först i listan.

  /api/revisions/[uuid]  

Hämta en revision via api:

  /[uuid]/[timestamp}]format=application/json  

RDF-data

Du kan hämta RDF-data för en enskild post i RDF/XML- och JSON-LD-format genom HTTP GET:

http://kulturnav.org/[uuid]  
Accept: application/rdf+xml  

eller

http://kulturnav.org/[uuid]  
Accept: application/ld+json  

Datadumpar i RDF/XML-format

Du kan använda sökvillkor för att definiera en export av en datadump. Läs mer om att exportera data. [sv]