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.

Using the API

Methods

More info

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)

Count 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]  

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  

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).
Sök kan genomföras mot två språkspecifika egenskaper och språket specificeras antingen i en parameter lang={språk-kod} eller via Accept-Language i headern (se ovan).

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

/api/search/nativeText:{sökfras}?lang={språk-kod}  

for example:

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

Name search - search through names/name fields in the specified language:

 /api/search/nativeCompoundName:{sökfras}?lang={språk-kod}  

for example:

/api/search/nativeCompoundName:Wilse?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  

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.

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.

Geo-data

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>  

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.