Core API
The KulturNav Core API is a simple API for reading and searching data.
The default response contains minimal data. More data can be opted in by parameters.
URL Syntax
https://kulturnav.org/api/core/{uuid|search expression}[/{offset}[/{number of records}]][?properties=]{property,...}[&displayValues={true|false}]][&labels={true|false}][&lang={no|nn|sv|en|fi|et}]
- uuid: UUID for a single record
- search expression: a KulturNav query string, examples below
- offset: offset in a paginated response
- number of records: max number of records in the response page
- properties: list of property types to include in the response
- caption: the entity's name including specification if available
- entity.fullCaption: the entity's full name including specification if available
- coordinates: geodata as a string - latitude and longitude
- entity.latitude and entity.longitude provide decimal values instead.
- entity.latitude and entity.longitude provide decimal values instead.
- specificType: detailed type specification, for example - concept category or type of place
- related: adds a simplified wrapping for entity synonyms (name data), hierarchy (part of), relations (related data) and matchings (same as, exact match)
- entity.list: shows which list(s) it is part of
- superconcept.begin: a birth, creation or establishment year
- superconcept.end: a death or termination year
- dataset.primaryLanguage: primary language for the dataset. You should expect property values in this language.
- entity-specific properties can be found at the bottom of the page
- caption: the entity's name including specification if available
- displayValues: include caption for reference properties, default value false
- labels: include label for property types and entity type name, default value false
- lang: preferred language for multi-language text
- most browsers provide a default language, but you can set this manually if needed
Response format
{
"hits": number of hits,
...
"entities": [
{
"uuid": entity UUID,
"createdAt": datetime...,
...
"name": entity name,
...
"properties": {
...
}
}
]
}
Examples
UUID:
A single data entry:
/api/core/8490f640-7c1b-4808-889a-6e5ea354f377
Search Expression:
The format for search expressions is as follows:
[propertyType]:[value]
Search expressions can be combined by separating each new expression with a preceding comma:
[propertyType]:[value],[propertyType]:[value]
Take care not to add any spaces before or after each comma to avoid breaking the url.
Multiple search expressions combine in a logical AND manner to return objects that fulfill every condition.
It's possible to search for objects that do not include a certain value, by prefacing the search value with "!":
[propertyType]:![value]
For number type properties it is also possible to use the less than and greater than symbols ('<' and '>'):
Less than: [propertyType]:<[value]
Greater than: [propertyType]:>[value]
Every person (first expression) with birthdate after 1970 (second expression):
/api/core/entityType:Person,superconcept.begin:>1970-Y
Every entity in the dataset "Eidsvollsmenn (Norsk Folkemuseum)":
/api/core/entity.dataset:72af60f0-9f9d-4586-9116-c666f3f20974
50 entities at the beginning of the list in the dataset "Eidsvollsmenn (Norsk Folkemuseum)":
/api/core/entity.dataset:72af60f0-9f9d-4586-9116-c666f3f20974/0/50
Retrieving the dataset "Eidsvollsmenn (Norsk Folkemuseum)", including each record's current status (the status is of type ENTITY_REFERENCE):
/api/core/entity.dataset:72af60f0-9f9d-4586-9116-c666f3f20974?properties=superconcept.status
Something to keep in mind for the above search - the ENTITY_REFERENCE type has the following response format:
{
"uuid": property uuid,
"valueType": "ENTITY_REFERENCE",
"value": value uuid
}
To follow the reference, in this case the superconcept status, use the value uuid and not the property uuid.
Every person in the "Eidsvollsmenn (Norsk Folkemuseum)" dataset, including their birth and death dates, with swedish text (lang=sv) for labels (labels=true) and other properties.
/api/core/entityType:Person,entity.dataset:72af60f0-9f9d-4586-9116-c666f3f20974?properties=person.birth,person.death&labels=true&lang=sv
Every person in the "Eidsvollsmenn (Norsk Folkemuseum)" dataset, including their birth and death dates.
/api/core/entityType:Person,entity.dataset:72af60f0-9f9d-4586-9116-c666f3f20974?properties=person.birth,person.death&displayValues=true
DisplayValues=true ensures that we can find the name values for things like the birthplace and where they died, where without that parameter we would see only the reference value.
I arbeid...