TMW-API Help API-Version: 1.0.2

Fileversion: 2021-07-27

Index

For detailed documentation see here.

Recent changes on the API

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:

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.

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:
	=title:"I am a string with whitspaces (and brackets)"

	; comma separated list of values:
	=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 . The range parameter can consist three values, start date , end date and the search type. 

	={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. 

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

	: 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

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 instead of the .

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

Example

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

In this example, the search is done in the fields , and , 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 = filter1[,filter2,...] string to the query by separating ist with the pipe character |.

Two filters are currently defined:

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 = all all field defined in the config.ini will be returned.

The following facets are defined in the config.ini:

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:

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:

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: