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 content
- Character encoding
- SOCH API
- List over the SOCH indexes that are valid for the methods statistic, statisticSearch, allIndexUniqueValueCount, and facet.
- Methods
Character Encoding
SOCH API used 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
Below the SOCH API is described. New methods and functionality will be added when required.
The SOCH API uses the REST web service principles. Applications send requests as parameters in the URL and get the result back as an XML file.
You can se 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 using 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 using 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: 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. There are also constants for the most used systems, ”RT90″, ”SWEREF99″, and ”WGS84″. The default value is SWEREF 99 TM (3006) if you don’t specify a system 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.
NOTE
- You compare the end search time with the fromTime element and the search start time with the toTime element. Check with boolean algebra if it 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 seems to be more divergent than it actually is. Compare the following two object representations: http://kulturarvsdata.se/shm/object/rdf/44361
http://kulturarvsdata.se/raa/fmi/rdf/12000000104766
If you take a closer look, the representations are quite different in structure. However, RDF is idiomatic in the way 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 over the SOCH indexes that are 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
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 the result 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 combination 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 possibility 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 facetted 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 a so-far-typed prefix.
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 correctly, 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. Both directions are found at 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 objects context to another object. The method returns name with reverse and Swedish title.
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”.
Example
http://kulturarvsdata.se/ksamsok/api?method=getRelationTypes&relation=all&x-api=test
getGeoResource
This method is not available yet. It will return information and polygons for parish, region, county and municipality. This is part of the SNHB goal to be a geografical 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 se how word stems are handled in SOCH.
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