API

KulturNav tilbyr et API for å søke i data som er lagret. Svaret er gitt i JSON-format.

Ny version av API ute nu: 1.5. Läs mer.

Få objekt via id

Man henter et enkelt objekt gjennom anropet

/api/[uuid]  

eller

http://kulturnav.org/<uuid>  
with HTTP header Accept: application/json  

der uuid er objektets uuid. Resultatet er et JSON-objekt med objektets data.

Hente datasett via id

Man henter alle objektene i et datasett gjennom anropet

 /api/list/[uuid]  

der uuid er datasetets uuid. Resultatet er en JSON-liste (array) med datasettets post først og deretter postene i datasettet.

Hente datasett med offset

Man henter en datamengde med begynnelsen fra et visst offset med anropet

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

hvor uuid er datasettets uuid og offset er fra hvilken posisjon i listen man vil hente fra. Om man vil hente fra det femte objektet og framover brukes offset 4.

Hente delmengde av datasett

Man henter en delmengde av et datasett med anropet

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

hvor uuid er datasettets uuid, offset er fra hvilken posisjon man vil hente (se Hente datasett via offset), og max er maks antall objekter man vil hente.

Søke data

Man kan søke etter objekt med anropet

 /api/search/[søkevilkår]  

Se Søkevillkår for en beskrivelse av syntaks for søkevilkår.

Resultatet er en JSON-liste (array) med objektenes data. Som standard returnerer anropet de 20 første søketreffene. Endre antall og startposisjon på samme måte som for Hente delmengde av datasett)

Regne søketreff

Man kan telle hvor mange objekter som oppfyller et søkevilkår med anropet

 /api/count/[søkevilkår]  

Se Søkevilkår for en beskrivelse av syntaks for søkevilkår.

Resultatet er et JSON-objekt:

{  
    "searchCrit": "[søkevilkår]",  
    "count": [antall treff]  
}  
Søkevilkår

Søkevilkår har formen

[feltnavn]:[verdi]  

flere vilkår kan kombineres med , (komma) mellom

[feltnavn]:[verdi],[feltnavn]:[verdi],[feltnavn]:[verdi]  

ved søking får man treff på de objektene som oppfyller samtlige vilkår (logiskt OCH).

For å angi at et felt ikke skal ha en viss verdi, angi et ! (utropstegn) før verdien

[feltnavn]:![verdi]  

For å angi at et felt skal ha en mindre eller større verdi angi < (mindre enn) eller > (større enn) foran verdien. Dette er først og fremst aktuelt for datosøking.

[feltnavn]:<[verdi]  
[feltnavn]:>[verdi]  

Feltnavn skal med noen unntak angis med en endelse som angir verditype (styrt av feltnavnsnotasjonen i søkeindekset) og eventuelt språk (for tekstegenskaper). Dette er ikke så intuitivt og kan bli endret. Noen eksempler:

  • superconcept.license_r (referanseverdi)
  • superconcept.isPlaceHolder_b (sant/falskt verdi)
  • entity.code_s (strengeverdi)
  • entity.name_no_t (tekstverdi, søk i språk norske)
  • dataset.contentUpdatedAt_dt (datoverdi, angi dato med formatet YYYYMMDD hhmmss-S)

Følgende grunndata behøver ingen endelse:

  • entityType (objekttype, med undertyper så matcher f.eks. entityType:Actor både personer, organisasjoner, dyr og navngitte gjenstander)
  • actualEntityType (objekttype, eksakt matching, f.eks. så matcher actualEntityType:Concept bare termer, ikke taksoner og stiler
  • createdAt (tidpunkt for når objektet ble opprettet, lik format som datofelt)
  • updatedAt (tidpunkt for når objektet sist ble oppdatert, lik format som datofelt)
  • savedAt (tidpunkt for når objektet ble opprettet eller sist oppdatert, lik format som datofelt)
  • createdBy (brukernavn på den som opprettet objektet)
  • updatedBy (brukernavn på den som sist oppdaterte objektet)
Eksempel på søkevilkår

Søk etter personposter med lisens CC-0:

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

Søk etter poster i datasettet "Fotografregisteret (Norge)" som ble opprettet eller oppdatert etter 21.april 2015:

/api/search/entity.dataset_r:508197af-6e36-4e4f-927c-79f8f63654b2,savedAt:>20150421 000000-S  

Søk etter poster i datasetet "Arkitekter verksamma i Sverige" som har Samme som-referenser til objekt i Wikidata:

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

Søk etter person med etternavn Aagaard i datasetet "Fotografregisteret (Norge)":

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