Version 1.1 (updated 2012-02-08)

This SOCH API is developed to enable the easy creation of advanced search applications. It contains, apart from the standard search method, methods for doing advanced statistic searches and methods for faceting, etc.

To use the API, you need an API key which can be obtained by e-mailing ksamsok [at] raa.se.

Table of contents

Character Encoding

The SOCH API uses UTF-8. Using any other character encoding may lead to incorrect search results or no results at all. A search page using the SOCH API must have contentType set to UTF-8:

<meta content=”text/html; charset=UTF-8” http-equiv=”content-type”>

The web form making the call to the API must have accept-charset set to UTF-8:

<form action=”www.kulturarvsdata.se/ksamsok/api?…” accept-charset=”UTF-8″>

SOCH API

The SOCH API is described below. New methods and functionality will be added when required.

The SOCH API uses RESTful web service principles. Applications send requests as parameters in the URL and results are returned as an XML stream.

You can see the results in XML, RDF, or stylesheet modified format using The flea demo application.

This document describes the URL for five different search examples:

  • free search
  • free search for object and place
  • search using specific elements
  • search within a geographical rectangle
  • time search

Example 1 – free text search

This call searches for the text ”Yxa” in a large number of elements of the RDF structure for the objects in SOCH. At most 10 hits are returned. Try the links above and below to see the URL and the resulting XML or styled data with different options.

Example 1 using SOCH API:
Show this search!

Example 1 with stylesheet: Show the search using a stylesheet!

Example 1 with pictures only: Show the search for objects having pictures only!

Example 2 – free text for object and place

This call searches for the text string ”Boplats” in all item related elements and for the text string ”Stenkyrka” in all place related elements. At most 3 hits are returned. Try the links above and below to see the resulting XML data with different options. See example 1 for how to use stylesheet or filtering options.

Example 2 using SOCH API: Show this search!

Example 3 – search using specific elements

This call searches for the text string ”Boplats” in the specific (detailed) element itemDescription and for the text string ”Stenkyrka” in the specific element parishName. At most 3 hits are returned. Try the links above and below to see the
resulting XML data with different options. See example 1 for how to use stylesheet or filtering options.

Example 3 using SOCH API: Show this search!

Example 4 – search for objects in a geographical rectangle

The principle is to search as follows, specifying the extremities of a bounding box: boundingBox=”west south east north”

This call searches for all objects within a geographical rectangle. Several coordinate systems are supported. Specify /EPSG:xxxx to select a specific system according to the EPSG Geodetic Parameter Registry. There are also constants for the most used systems, ”RT90″, ”SWEREF99″, and ”WGS84″. The default value is SWEREF 99 TM (3006) if no other system is specified with the ”/” modifier. The above example is an RT90 search.

The decimal sign must be a dot (not a comma).

Example 4 using SOCH API: Show this search!

Example 5 – search for objects in a specific time frame

This is an example of a call that searches objects from the 17th century.

NB

  • You compare the end search time with the fromTime element and the search start time with the toTime element. (Check your boolean algebra if this sounds strange!)
  • fromTime and toTime don’t work well however; you should decide what context type to use, e.g. create_fromTime and create_toTime.
  • Many objects in SOCH have no time specification.

http://kulturarvsdata.se/ksamsok/api?method=search&hitsPerPage=10
&x-api=”test”&stylesheet=../stylesheet/searchStyle.xsl
&query=create_fromTime<=1699 and create_toTime>=1600

SOCH – a very Heterogeneous Data Set

At the RDF level the data set appears to be more divergent than it actually is. Compare the following two object representations:

If you take a closer look, the representations are quite different in structure. However, RDF is idiomatic in the sense that you can build the same structure in different ways. In the semantic web the two objects follow the same schema and are composed in the same way. One of the objects has values for some parameters and the other object has values for other parameters, but that is another issue altogether.

List of SOCH indexes valid for the methods statistic, statisticSearch, allIndexUniqueValueCount, and facet.

Entity (Object) Parameters

An entity is a searchable object in SOCH. It could be an ancient object, a cultural environment, a piece of art, a photograph, a book, or anything else that a content provider in a cultural heritage institution chooses to deliver. An entity is implemented as an RDF resource with a persistent URI in the format domain/institution/service/id, e.g. http://kulturarvsdata.se/raa/fmis/12345. The first table below lists the general elements for an entity.

serviceName
Description
serviceOrganization
Description
collection Description
theme
Description
subject
Description
mediaType
Description
dataQuality
Description
itemType
Description
itemClass
Description
itemMotiveWord
Description
itemMaterial Description
itemTechnique
Description
itemColor
Description
itemLicense
Description

Time Parameters

The time related elements and parameters are connected to the object through a specific event or content, e.g. ”create”. There can be several contents for an object. Below is a description of the time parameters.

contextType
Description
fromPeriodName
Description
toPeriodName Description
fromPeriodId
Description
toPeriodId
Description
periodAuth
Description
eventName
Description

Place Parameters

The place related elements and parameters are connected to the object through a specific event or content, e.g. ”find”. There can be several contents for an object. Below is a description of the place parameters.

continentName
Description
county Description
province
Description
municipality
Description
parish
Description
countryName
Description
countyName
Description
provinceName
Description
municipalityName
Description
parishName Description

People/Organization Parameters

The actor related elements and parameters are connected to the object through a specific event or content, e.g. ”reproduced”. There can be several contents for an object. Below is a description of the actor parameters.

The elements for people or organizations describes a certain context for the object, e.g. ”produced”. There can be several such contexts defined for an object. Below are the elements for actor contexts.

firstName
Description
organization
Description
title
Description
gender
Description
nameId
Description
nameAuth
Description

Other indexes

thumbnailExists
Description

SOCH API Methods


Common Parameters

These parameters are used by several or all API methods.

Parameters

query
What to search for. The API uses CQL syntax for queries.

Example: query=item=”sten yxa” AND place=gotland NOT itemMaterial=brons

index
This parameter decides what indexes the method should be used on. There is no limit on the number of indexes specified, but a lot of indexes with a lot of unique values can influence performance.

Example: index=mediaType=*|itemName=yxa*

stylesheet (optional)
Specifies if an XSLT stylesheet should be used to present the results. See the examples for the different methods to find out what stylesheets to use. The different stylesheets are adapted to different API methods.

Example: stylesheet=stylesheet/searchStyle.xsl

removeBelow (optional)
Combinations of unique values that have a number of records below this number will not be returned in the XML answer.

Example: removeBelow=3

x-api (mandatory)
Specifies which API key to use. If you don’t have an API key, you can use the value ”test” while waiting for a real key. The keys are used for statistics and can also be used to handle any DoS attacks.

Example: x-api=test

Search

The search method performs a search for objects in SOCH.
The result is an XML answer with a number of objects.

Parameters

query (mandatory)

hitsPerPage (optionally)
Specifies how many hits to show in one page. The parameter is a numeric value between 1 and 500. Default is 50.

Example: hitsPerPage=12

startRecord (optional)
Specifies what part of the result set to return. The default is to fetch objects 1–50. If you specify startRecord=11 you will get the objects 11–60 (assuming that hitsPerPage is 50).

Example: startRecord=50

stylesheet (optional)

sort (optional)
Specifies that results should be ordered according to a specific index.

Example: sort=itemType

sortConfig (optional)
Specifies if the sort should be ascending or descending.
Allowed values are: asc and desc

Example: sortConfig=desc

recordSchema (optional)
Specifies which record schema to use. At present only one schema is available (presentation). If you specify recordSchema=presentation, then only presentation data is returned (summary information about the objects. If the parameter is not specified, all data about the objects is returned.

Example: recordSchema=presentation

Example
Here is an example of a search method request:

www.kulturarvsdata.se/ksamsok/api?method=search&stylesheet=stylesheet/searchStyle.xsl&query=item=yxa&place=gotland&startRecord=10&hitsPerPage=25&sort=itemName&sortConfig=asc&recordSchema=presentation&x-api=test


Statistic

This method returns a list with all combinations of all unique values for specified indexes, as well as the number of hits for each combination.

Parameters

index (mandatory)

stylesheet (optional)

removeBelow (optional)

Example
This is an example statistic method request:

www.kulturarvsdata.se/ksamsok/api?method=statistic&stylesheet=stylesheet/statistic.xsl&index=mediaType=*|itemName=yxa*&removeBelow=3&x-api=test


statisticSearch

This method resembles the statistic method, except for the option to filter the result with a query. In other words it is a combination of the search and statistic methods.

Parameters

index (mandatory)

stylesheet (optional)

query (mandatory)

removeBelow (optional)

Example

This is an example statisticSearch method request:

www.kulturarvsdata.se/ksamsok/api?method=statisticSearch&stylesheet=stylesheet/statistic.xsl&index=serviceOrganization=*&query=itemLabel>talk and itemLabel<talm&removeBelow=1&x-api=test


allIndexUniqueValueCount

This method returns a list of relevant indexes and the number of unique values for those indexes, given a specified query.

Parameters

query (mandatory)

index (optional)

stylesheet (optional)

Example
Here is an example of an allIndexUniqueValueCount request:

www.kulturarvsdata.se/ksamsok/api?method=allIndexUniqueValueCount&stylesheet=stylesheet/allIndexUniqueValueCount.xsl&query=yxa&index=itemType|provinceName|serviceOrganization|thumbnailExists&x-api=test


facet

This method performs a faceted search for specified indexes and a filtering query.

Parameters

index (optional)

query (mandatory)

stylesheet (optional)

removeBelow (optional)

Example:
A search using the facet method can look like this:

www.kulturarvsdata.se/ksamsok/api?method=facet&&stylesheet=stylesheet/facet.xsl&index=countyName|thumbnailExists&query=hus&removeBelow=1&x-api=test


searchHelp

This method is developed to accomplish auto text when a search is typed in a user interface. It returns suggestions of words given the prefix typed so far.

Parameters

index (mandatory)

prefix (optional)
Specifies the prefix to be used for the search. If not specified the prefix is set to *. If a prefix is sent without a trailing *, the * will be appended automatically, i.e. ”sto” will be changed to ”sto*”.
Example: prefix=sto*

stylesheet (optional)

maxValueCount (optional)

Specifies the number of suggestions you want for each index. If set to e.g. 5, you will get 5 suggestions for each index sent (provided there are that many values available). Default is 3.
Example: maxValueCount=5

Example

www.kulturarvsdata.se/ksamsok/api?method=searchHelp&stylesheet=stylesheet/searchHelp.xsl&index=itemMotiveWord|itemKeyWord&prefix=sto*&maxValueCount=5&x-api=test


rss

This method returns an RSS feed from SOCH (or more accurately, a MediaRSS feed). The method works just like the search method except for the result formatting.

Parameters

See the parameter description for the search method.


getServiceOrganization

This method returns information about the institutions providing information to SOCH. The information is maintained by the institutions themselves.

Parameters

value (mandatory)
This parameter specifies which institution you want to fetch information about, e.g. raä for SNHB. If you don’t know the different acronyms or if you need information about all institutions, you should use the value ”all”.

Example

http://www.kulturarvsdata.se/ksamsok/api?method=getServiceOrganization&value=all&x-api=test


getRelations

This method can be used to list all or some relations for an object. Not only the relations in the RDF data for the current object are returned, but also relations to the current object that are specified in other objects’ RDF data. This means that relations never need to be bidirectional at the data level: relations in both directions are found at the application level anyway through this call to the getRelatons method.

Parameters

relation (mandatory)
With this parameter you specify which relation type you want to list. If you want to see all relation types you specify ”all”. In the result set some relations could be attributed as ”deduced”. This implies that the object was found in another objects RDF data, not in the requested objects RDF data.

uri (mandatory)
The persistent URI for the object.

maxCount (optional)
Maximum number of returned relations.

Example

http://kulturarvsdata.se/ksamsok/api?method=getRelations&relation=all&objectId=raa/fmi/10028201230001&maxCount=1000&x-api=test


getRelationTypes

This method can be used to list the relations from an object’s context to another object. The method returns the name of the relation, along with its corresponding reverse (inverse) and Swedish titles.

Parameters

relation (mandatory)
With this parameter you specify which relation type you want to list. If you want to see all relation types you can specify ”all”.

Example

http://kulturarvsdata.se/ksamsok/api?method=getRelationTypes&relation=all&x-api=test


getGeoResource

This method is not yet available. In the future it will return information and polygons for parish, region, county and municipality. This is part of the SNHB’s goal to be a geographical authority, not only towards SOCH but towards other parties that need those services.

Parameters

uri (mandatory)
This parameter specifies the persistent URI for the resource.

Example:

http://kulturarvsdata.se/ksamsok/api?method=getGeoResource&uri=http://kulturarvsdata.se/resurser/aukt/geo/municipality%230117&x-api=test


stem

This is a simple method to see how word stems and inflection/declension are handled in SOCH; it returns the stem of the word specified.

Parameters

words (mandatory)
This parameter specifies which word(s) you want to check the stemming for.

Example:

http://www.kulturarvsdata.se/ksamsok/api?method=stem&words=kappe&x-api=test