TMW-API Help

API-Version: 1.0.2

Fileversion: 2021-10-19

For detailed documentation see here.

Recent changes on the API

• 2019-02-11: New format 'turtle' for objects, persons and thesaurus
• 2016-01-12: New format 'thumbsquare' for images fitted in a square
• 2015-11-24: quotes in query string when includes special characters
• 2015-11-03: linkedData block unified for different sources
• 2015-10-20: web structure data block for website display added
• 2015-10-16: level and extent added in object facet for archive objects

The TMW-SolR api retrieves data from the Solr-database containing all information about objects, persons/institutions, thesaurus and exhibitions. The data can be returned in different formats. If no format is defined, a html page is displayed.

For easy use, the api is configured with a webserver url rewrite engine. For setting up the rewrite engine, see the documentation.

Data retrieval

Single record retrieval

For data retrieval of a single record the simple pair of domain-id can be used. The query parameter is reduced to the integer of the id. The uri format is:

{domain} [/{preprocessor}]/ {ID} [/{format}[/{language}]]

Without a format definition the defaultFormat setting is used.

If a language code is added, the format has to be defined.

The TMW-API offers four domains:

• object - metadata of object and archiv
• thesaurus - poyhierarchic thesaurus
• person - metadata about person/institution

Examples

One record from the object domain in different formats:

	https://data.tmw.at/object/164392# (default format)
	https://data.tmw.at/object/164392/rdf
	https://data.tmw.at/object/164392/xml
	https://data.tmw.at/object/164392/xml/en (with additional language parameter)
	

Query based retrieval

For data retrieval using the search functionality, a query string has to be used instead of the ID:

{domain} [/{preprocessor}]/ {queryString} [/{format}[/{language}]]

The query string can contain the following parameters seprated by the pipeline character |. The query string should be the first and can also be given in the simplified format.

• query={field}:{value} AND/OR/NOT {...}:{...}
• start={integer} - first record to get
• limit={integer} - maximum number of records
• filter={filter_list} - list of predefined filters
• facet={field}[,{field}] / all
• range={start_date},{end_date}[,search_type]

If the query field search value contains any special characters, like brackets, whitespaces, etc., the string must be enclosed by double quotes. This also is necessary for a comma separated list of values.
In the case, that no special character are present, or when using a list of comma separated ids, quotes are not needed (but can have it too).

	; query string with special characters:
	query=title:"I am a string with whitspaces (and brackets)"

	; comma separated list of values:
	query=title:"Haus mit Dach,Dampf*"

	; only a list of ids:
	30123,30125
	"30123,30125"

Examples

	https://data.tmw.at/object/query=title:*Silberpfeil*
	https://data.tmw.at/object/title:*Silberpfeil*|limit=2/rdf
	https://data.tmw.at/object/164392/xml
	https://data.tmw.at/object/query=title:*Silberpfeil*/xml/en (with additional language parameter)
	

Range Search

A date range search is supported with the extra parameter range. The range parameter can consist three values, start date , end date and the search type.

	range={start_date},{end_date}[,{search_type}]
	

The type determines, how the date range is used to find corresponding records. If no type is defined, outer is used by default. The parameters for the field names in solr and the default search type are defined in the range.ini file.

	inner: start_date and end_date have to be inside the object start/end dating.
		
		Object dating       start |------------------------| end
		Search dates       start_date |-----------| end_date
	

	outer: start_date or end_date have to be inside the object start/end dating,
		
		Object dating               start |---------------------| end
		Search dates     start_date |-----------| e._d.  s_d. |-----------| end_date

	or the object dating range is completely inside the search dates.
		
		Object dating               start |------------| end
		Search dates    start_date |------------------------| end_date
	

Examples

	https://data.tmw.at/object/query=*:*|range=1850,1900,inner
	https://data.tmw.at/object/query=*:*|range=1850,1900,outer
	

Predefined Search

A predefined search is a query string, set up in an ini file, where the search string is represented by {} . If the predefined search is called, the API replaces these characters with the search string. Euch predefined search is called using the search instead of the query.

The search definition is done in the config/search.ini.

Example

	[object]
	default = "object_name_broader:*{}* OR title:*{}* OR description:*{}* OR object_number:{}*"
	

In this example, the search is done in the fields object_name_broader, title and description, using left and right side truncation in all cases.

	https://data.tmw.at/object/search=default:dampf*
	

Predefined Filter

It is possible to set up global filters for each domain stored as {domainName}.ini in the config directory. In each config file multiple filters can be defined, witch can contain include and exclude parameters. Includes are AND joined with the query, Excludes are AND NOT joined.

The filters are used by adding the filter = filter1[,filter2,...] string to the query by separating ist with the pipe character |.

Two filters are currently defined:

• media: all records with a minimum of one image
• exhibited: all objects currently in an exhibition

Examples

	https://data.tmw.at/object/object_name_broader:personenkraftwagen
	https://data.tmw.at/object/object_name_broader:personenkraftwagen|filter=exhibited
	

Multiple filters are AND joined. A filter is a global preselection and can be combined with any spezial query string.

Facet

The facet parameter can contain a comma separated list of fields. With facet= all all field defined in the config.ini will be returned.

The following facets are defined in the config.ini:

• date - time periods
• object - object names
• subject - conceptual and technical subjects
• event - all kind of events
• creator-role - role of a person/institution in respect to an object
• occupation - occupation of a person
• geography - geographical expressions
• title - full text index on the title string
• description - full text index on the description string

Format

With the format parameter the output of the api can be controlled. Without a format definition the defaultFormat set in the config.ini.

There are several formats available for the different demains:

• html - html page
• xml - TMW api xml format
• rdf - open data RDF
• link - only the links of a record in xml/json/php
• json - convert xml to json
• php - convert xml to php array
• media - only media metadata of a record
• thumb/preview/big - binary media stream in different resolutions

Language

By adding a language code as last parameter, the data is returned in the corresponding language. If this language does not exist, the default language is returned instead. The default language code is set in the config.ini.

The supported language codes are:

• de (default)
• en

Preprocessor

The preprocessor can be used to change data loaded from the SolR database, before it is transformed in the output format. The following preprocessors are available:

• linkchecker - checks broken internal links
• link - resolve internal links
• resolve - resolve external links
• topterm - walk hierarchy to topterm