KSamsök-PHP

Looking for the official K-Samsök(SOCH) API documentation?

This documentation was last updated for KSamsök-PHP version 0.9.0

Introduction

KSamsök-PHP is a PHP library for the K-Samsök(SOCH) API. The K-Samsök aggregator has more then 6 million cultural objects indexed from various sources.

KSamsök-PHP is licensed under MIT and you can contribute to the project through Github.

Install

Composer:

Run the following command in your project root:

				composer require abbe98/ksamsok-php
PHP require()

If you are not able to use Composer you can simply require the file kSamsok.php.

Usage

The API requires a API key that you can obtain by contacting the Swedish National Heritage Board. For development you can use the key test.

Create a new instance of the KSamsok class and include your API key.

Examples

Basic example.

				$kSamsok = new KSamsok('test');

Usage example with custom K-Samsök endpoint.

				$kSamsok = new KSamsok('test', 'https://example.com/endpoint');

Public Methods

The basic search() method has a total of four parameters:

Examples

Searching for the string Fiskmås returning 60 results starting at te first result:

				$kSamsok->search('Fiskmås', 1, 60);

Searching for the string stockholm vattentorn only returning results with images, starting at result 60 and getting 400 results:

				$kSamsok->search('stockholm vattentorn', 60, 400, true);

Geo Search

The method geoSearch() allows you to search by a geographical bounding box. geoSearch() has six parameters:

Examples

Search by small bounding box in Sörmland, starting at the first result:

				$west = '16.41';
				$south = '59.07';
				$east = '16.42';
				$north = '59.08';
				$kSamsok->geoSearch($west, $south, $east, $north, 1);

Search in the same bounding box as above but return 500 results starting at result 300:

				$west = '16.41';
				$south = '59.07';
				$east = '16.42';
				$north = '59.08';
				$kSamsok->geoSearch($west, $south, $east, $north, 300, 500);

Search Hint

The searchHint() method allows you to return search suggestions from a string. This method has two parameters:

Examples

Get five suggestions for the string ny:

				$kSamsok->searchHint('ny');

Get three suggestions for the string ka:

				$kSamsok->searchHint('ka', 3);

Relations

The relations() method allows you to return a list of object related to another. The method has only one parameter:

Raw URLs/URIs such as:

HTML, JSONLD, RDF, XML resource URLs/URIs:

Example

Get all relations for the object raa/fmi/10028201230001:

				$kSamsok->relations('raa/fmi/10028201230001');

Object

The object() method returns a object based on a URI or URL. The method has only one parameter:

Raw URLs/URIs such as:

HTML, JSONLD, RDF, XML resource URLs/URIs:

Example

Return the object shm/18797 based on the URL to its XML source:

				$kSamsok->object('http://kulturarvsdata.se/shm/site/xml/18797');

URI Format

The uriFormat() method can validate and convert SOCH URI/URL;s. uriFormat() will return false if provided with a invalid URI. uriFormat() has three parameters:

Example

Get the XML source URL from the raw URI shm/18797:

				$kSamsok->uriFormat('shm/site/18797', 'xmlurl');

Advanced Usage

Extending

When KSamsök-PHP does not have a method for a request you want to preform against the K-Samsök API extending KSamsök-PHP might be the solution. Extending KSamsök-PHP allows you to use KSamsök-PHP functions for formating URIs, validate responds, parsing and more, together with your own custom requests.

Note that this may require that you are familiar with The K-Samsök(SOCH) API.

Extending: Introduction

Extending KSamsök-PHP is done using PHP extended classes and the extends keyword. Extending K-Samsök does not support JSON-LD responses by default.

				customKSamsok extends kSamsok {
					// your custom methods
				}

killXmlNamespace()

Because the KSamsök-PHP parsing function does not support XML Namespaces killXmlNamespace() is used to over ride them.

Example

Over ride the XML Namespaces in respond:

				customKSamsok extends kSamsok {
					public function customMethod($url) {
						$xml = file_get_contents(utf8_decode($url));
						if ($xml) {
							$xml = $this->killXmlNamespace($xml);
						}
					}
				}

parseRecord()

The parseRecord() does parse a single record(SimpleXMLElement object) in XML format and returns it as a single PHP object.

Example

Parse all returned records and push them to result array:

				customKSamsok extends kSamsok {
					public function customMethod($url) {
						$xml = file_get_contents(utf8_decode($url));
						if ($xml) {
							$xml = $this->killXmlNamespace($xml);
							$xml = new SimpleXMLElement($xml);
							$result[] = array();
							foreach ($xml->records->record as $record) {
								$result[] = $this->parseRecord($record);
							}
						}
					}
				}

Extending: Example

The following example makes a text search for all results with images and then just returns the ones that does not have any coordinate data:

				customKSamsok extends kSamsok {
					public function photoSearchNoCoords($text) {
						$url = $this->url . 'x-api=' . $this->key . '&method=search&hitsPerPage=250&query=itemType="Foto"%20and%20text="' . $text . '"%20and%20mediaType="image/jpeg"%20and%20thumbnailExists=j&recordSchema=presentation';
						$xml = file_get_contents(utf8_decode($url));
						if ($xml) {
							$xml = $this->killXmlNamespace($xml);
							$xml = new SimpleXMLElement($xml);
				
							$firstResults[] = array();
							foreach ($xml->records->record as $record) {
								$firstResults[] = $this->parseRecord($record);
							}
				
							if (!empty($firstResults)) {
								for ($i=0; $i < count($firstResults); $i++) {
									if (empty($firstResults[$i]['presentation']['coordinates'])) {
										$results[] = $firstResults[$i];
									}
								}
							}
				
							return $results;
						} else {
							return false;
						}
					}
				}