Description of the API
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.
Table of contents
- Character encoding
- SOCH API
- List of SOCH indexes valid for the methods statistic, statisticSearch, allIndexUniqueValueCount, and facet.
- Methods
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
&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
- search
- statistic
- statisticSearch
- allIndexUniqueValueCount
- facet
- searchHelp
- rss
- getServiceOrganization
- getRelations
- getRelationTypes
- getGeoResource
- stem
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
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
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
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
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
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
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
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
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
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
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