API

KulturNav offers an API for searching through stored data. The API currently supports HTTP GET requests to read data. The search result is delivered in JSON-format. API calls are currently not authenticated or authorized. This means only published content readable for ANY user is returned.

Changelog

Using the API

Methods

More info

Version your API request

We plan to update and change KulturNav's API in early 2025 (version 2.0). To ensure that your apps work after the update, you should make sure to version your API requests by adding the current API version, /v1.5/, to the call (i.e. /api/v.1.5/) until you have adapted your apps to version 2.0.

/api/[current_version]/[method]  

Retrieve an object using its id

You can retrieve a single entity by using the query

/api/[uuid]  

where uuid is the object's uuid. The result is a JSON object containing the object's data. You can also retrieve the JSON object by adding the file type suffix .json at the end of the URI.

/[uuid].json  

If you make a query with an Accept-header, you can retrieve the JSON object by specifying application/JSON.

Retrieve entities in a dataset with api/list

It's possible to retrieve all objects in a dataset with the query

 /api/list/[uuid]  

where uuid is the dataset's uuid. The search result is a JSON list (array) with the dataset's item first, followed by each item in the dataset.

Retrieve a dataset with offset

It's possible to retrieve parts of a dataset beginning from a certain offset point with the query

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

where uuid is the dataset's uuid, and offset represents where in the dataset the list should start.

The offset is zero-based, meaning that the first entity in the list is assigned the index 0. To retrieve entities starting with the 5th object, use an offset value of 4.

Retrieving parts of a dataset - limiting number of posts returned

It's possible to further narrow down a search query to retrieve only a subsection of a dataset with the query

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

where uuid is the dataset's uuid, offset represents where in the dataset the list should start, and max is the total number of objects/items you want to retrieve.

Retrieve only the properties you require with api/core

You can retrieve specific properties from an entity or a search by using api/core.
This api returns minimal information about the entity by default, but can be customized to contain only the properties you require by using the properties parameter

/api/core/{uuid|property:value,...}[/{offset}[/{number of records}]][?properties={property,...}[&displayValue={true|false}]][&labels={true|false}][&lang={no|nn|sv|en|fi|et}]

You can find more complete documentation about api/core, its characteristics and how to use its search syntax here.

Retrieve summaries with api/summary

It's possible to retrieve a summary of key properties from an item, list, dataset or search:

/api/summary/<uuid for item>  

returns the item's summary-JSON. Keep in mind that even if you only retrieve a single item you will still receive a JSON-array.

/api/summary/<uuid for dataset>  

returns a summary-JSON of the dataset's content.

For pagination:

/api/summary/<uuid for dataset>/<offset>/<number of items>  

search result:

/api/summary/<search criteria>  

returns a summary-JSON of the search result. Optional pagination functions the same as for datasets.

Retrieve complete data with api/search/

You can search for a specific object with the query

 /api/search/[search criteria]  

See Search criteria for a description of syntax for search criteria.

The return result is a JSON list (array) containing the object's complete data. The query returns the first 20 hits by default. You can change the number of hits and start position as described in Retrieving parts of a dataset)

Search for input with api/autocomplete

You can use the autocomplete API to search for entities of a specified class (entityType) and property (propertyType) by a query string (query) and optionally for entities in a dataset or a list (dataset). Only published records are returned.

/api/autocomplete?entityType={entityType}&property={propertyType}[&dataset={dataset or list uuid}]&query={query string}[&lang={no|nn|sv|en|fi|et}]  

Example:

/api/autocomplete?entityType=Concept&propertyType=compoundName&query=Bygn*  

The returned result is up to two JSON lists (arrays) containing uuid, entity caption and dataset information for maximum 200 records per list:

  • List 1 (fullMatch): entities that match a tokenized search in the specified property.
  • List 2 (startMatch): entities that match a tokenized search as above AND where the property value begins with the same letter as the search string .

An entity returned in a list:

{  
    "uuid": "[uuid]",  
    "caption": "[caption]",  
    "datasetUuid": "[dataset uuid]",  
    "datasetCaption": "[dataset caption]"  
}  

Count entitites in search results with api/count

You can find out how many objects fulfill the search criteria with the query

 /api/count/[search criteria]  

See Search criteria for a description of syntax for search criteria.

The result is a JSON-object:

{  
    "searchCrit": "[search criteria]",  
    "count": [number of hits]  
}  

Access to entity version history with api/revision

Shows a list with the entities's revision history, ordered from latest to first.

  /api/revisions/[uuid]  

Retrieve a revision via API:

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

API-version

Returns the last version of the API used by default.

/api/version  

Id list with the ?idonly parameter

A parameter in API-search: idonly reduces the return value of the query to an id list - for example:

/api/search/entityType:Agent,compoundName:Wilse?idonly  

Search criteria

Search criteria have the format

[field name]:[value]  

Several criteria can be combined using a comma between each criterion.

[field name]:[value],[field name]:[value],[field name]:[value]  

the search will return only objects that fulfill every single criterion (logical AND)

To specify that a field should not have a certain value, add a ! (exclamation mark) before the value.

[field name]:![value]  

You can use a property several times to create an AND NOT search:

[field name]:[value],[field name]:![value]  

To specify that a field should have a smaller or greater value, use < (less than) or > (greater than) before the value. This is mainly relevant for date searches.

[field name]:<[value]  
[field name]:>[value]  

Starting with version 1.5, field names can be used with or without an extension that indicates value type (controlled by the field name notation in the search index) and any language (for text properties).
When searching for inline elements, however, the value type must be specified.

Without value type:

  • The reference value (uuid) is entered with the field name, i.e. superconcept.license
  • True/false value is entered with the field name, i.e. Superconcept.isPlaceHolder
  • A string value is entered with the field name, i.e. entity.code
  • A text value is entered with the field name, i.e. entity.name. Language is now handled in a separate parameter, see below.
  • For date value only the field name is entered, i.e. dataset.contentUpdatedAt

With value type:

  • superconcept.license_r (reference value)
  • superconcept.isPlaceHolder_b (true/false value)
  • entity.code_s (string value)
  • entity.name_no_t (text value, searching in norwegian)
  • dataset.contentUpdatedAt_dt (date value, enter date in the format YYYYMMDD hhmmss-S)

The following basic data require no extension:

  • entityType (object type, returns matching sub-types, i.e. entityType:Actor - people, organizations, animals and named objects)
  • actualEntityType (object type, exact match, actualEntityType:Person, for instance, matches only people and not any sub-types)
  • detailedType (category in the form of a reference to a type of concept)
  • createdAt (point in time when the object was created, date format)
  • updatedAt (point in time when the object was last updated, date format)
  • savedAt (point in time when the object was created or last updated, date format)
  • createdBy (username of the person who created the object)
  • updatedBy (username of the person who last updated the object)

OR-conditions:

Search with OR for a specified property:

/api/search/{property}:{value1} OR {value2}  

for example:

/api/search/entityType:Agent OR NamedObject  

AND NOT-conditions:

/api/search/{property1}:{value1},{property1}:!{value2}  

for example:

/api/count/person.liferole.person.liferole.liferole:52201b97-a3c7-43ea-a1ee-e633480d55e8,person.liferole.person.liferole.liferole:!da7f057a-9ed6-4e92-b501-7aab7d8465cc  

Searching for strings of text

/api/search/{property}:"{text}"  

for example:

/api/search/text:"Swedish music group ABBA",entityType:Person  

Language handling

Language is specified in version 1.5 with the query parameter ?lang={language-code} or with header Accept-Language: {language}.

Parameter example:

 ?lang=sv  

Header example:

 Accept-Language: sv  

In the past, language handling was specified at the property level in connection with value suffixes (see above).

Language-specific search

Searches can be performed against two language-specific properties, and the language is specified either in a parameter lang={language-code} or via Accept-Language in the header (see above).

Free text search - search through all fields in the specified language:

/api/search/nativeText:{query}?lang={language code}  

for example:

/api/search/nativeText:Bord*?lang=no  

Name search - search through concept names fields in the specified language:

 /api/search/nativeCompoundName:{query}?lang={language code}  

for example:

/api/search/nativeCompoundName:Allsong?lang=no  

Search criteria examples

Count the number of person entities licensed with license CC-0:

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

Search for person entities with license CC-0, retrieving the first 100 entities:

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

Count the number of entities in the "Arkitekter verksamma i Sverige" dataset, created or updated after the 1st of April 2014:

/api/count/entity.dataset:2b7670e1-b44e-4064-817d-27834b03067c,savedAt:%3E20140401%20000000-S  

Search for entities in the "Arkitekter verksamma i Sverige" dataset, created or updated after the 1st of April 2014, retrieving the first 20 entities:

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

the next 20 after that:

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

Search for entities in the "Arkitekter verksamma i Sverige" dataset containing Same as-references to objects in Wikidata and get the first 20 entities:

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

Search for people with the last name Aagaard in the "Fotografregisteret (Norge)" dataset, and return an easy to work with number of elements:

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

Language specific autocomplete lookups for names or concepts using the nativeCompoundName property:

Norwegian Bokmål: "Allsang"

api/autocomplete?entityType=Concept&propertyType=nativeCompoundName&query=Allsa*&lang=no  

Norwegian Nynorsk: "Allsong"

api/autocomplete?entityType=Concept&propertyType=nativeCompoundName&query=Allso*&lang=nn  

Swedish: "Allsång"

api/autocomplete?entityType=Concept&propertyType=nativeCompoundName&query=Alls%C3%A5*&lang=sv  

Data

Information about an entity is returned in a JSON-structure. Contents, property names, can be viewed in schema. For further info about properties check out the api/core pages .

Entities in KulturNav's API

There are three main object types in KulturNav:

  • Dataset. Records are managed and stored in datasets. A dataset is a collection of records. A record is only managed in one dataset (but can be displayed in several). Read more about datasets.

  • List. Subclass for dataset. Contains a selection of records or datasets that are collected in users' own lists/folders. A record can be found in many lists/folders. Read more about lists/folders.

  • Individual records of different entity types: which can be actors (Agent), terms (Concept), named objects (NamedObject), time intervals (Time) and places (Place) with subclasses. The structure is found in schema.

Read more about information in KulturNav.

Deprecated records

Read more about deprecaded and replaced records.

About time properties

Information about time, i.e. a point in time in a time interval, is returned in the form of a string with precision indicators.

Year, for example 1999:

value: "1999-Y"  

Year-Month, for example December 1999:

value: "199912-M"  

Year-Month-Day, for example the 31st of December 1999:

value: "19991231-D"  

Uncertain dates are specified with a question mark (?) after the time specification, for example 1999?:

value: "1999?-Y"  

Unknown time is indicated with a question mark (?):

value: "?"  

Ongoing time is indicated with an exclamation mark (!):

value: "!"  

Read more about unknown, uncertain and ongoing time.

Geodata

You can retrieve a streamed GeoJSON from a dataset or a folder containing records with coordinates with the syntax:

/<uuid>.geojson  

or:

/api/geoJSON/<dataset-uuid>  

You can retrieve a GeoJSON from a en localized entity with the syntax:

/<uuid>.geojson  

or:

/api/geoJSON/<uuid>  

Images

In KulturNav an entity can be visualized by zero, one or many images. Images could be linked, uploaded or gathered from DigitaltMuseum's API (if the entity is depicted in the image) and cached as external data.

In /api/core

You retreive images from the the superconcept.imageEntities property. All image types are included in the element.

  • if the property superconcept.imageEntities...image.imageLink is present, the image is linked to an external image source.
  • if the property superconcept.imageEntities...image.image.originalFileName is present, the image is uploaded.
  • else if the property superconcept.imageEntities...image.image is present, the image is fetched from DigitaltMuseum's API (cached).

In all other api methods

You retreive images from different properties:

  • Linked and uploaded images are retrieved from the superconcept.imageEntities property.
  • Images fetched from DigitaltMuseum are retrieved from the superconcept.additionalData...superconcept.imageEntities property.

RDF-data

You can retrieve RDF-data for an individual record or dataset in RDF/XML and JSON-LD-format using HTTP GET:

RDF+XML

http://kulturnav.org/<uuid>  
Accept: application/rdf+xml  

or:

/<uuid>?format=application%2Frdf%2Bxml  

or:

/<uuid>.rdf  

JSON-LD

http://kulturnav.org/<uuid>  
Accept: application/ld+json  

or:

/<uuid>?format=application%2Fld%2Bjson  

or:

/<uuid>.json-ld  

Data dumps in RDF-format

You can use search criteria to define an export of a data dump. Read more about exporting data.

DCAT-AP

Datasets that dataset maintainers choose to publicize through DCAT-AP are available in an endpoint. Read more.