-
Notifications
You must be signed in to change notification settings - Fork 1
Mus api
Api definition for the MuS museum search service
The MuS search engine is dedicated museum object search engine based on Apache Solr. It focusses on performing a full text search on only 5 fields: who, what, where, when and how. Simple queries can be performed on these fields using the mus_sq parameter. The more powerfull mus_aq parameter allows for queries across these fields. Because a substantial subset of the Solr parameters just work, it is possible to create a custom solr query. This however, will not offer the power of the specialized MuS interface, for the MuS interface is highly optimized for retrieving relevant items.
A MuS query has one of the following parameters:
- mus_sq: MuS simple search query
- mus_aq: MuS advanced search query
It is important to know that these queries exclude eachother. Therefor only one of the queries will be performed if both are given. If the two possible query parameters are present in the request, this is the order of precedence: mus_sq, mus_aq. The first one is performed, the others are ignored. So if in a request the parameters mus_ss and mus_aq are present, mus_ss is performed, mus_aq is ignored.
Although searching takes place in only 5 fields, there are more fields for displaying the search result and for faceting. A complete list of available fields can be found later in this document.
The queries only support simple operations like + and – for requiring or excluding keywords and “” for exact matches. Complex Lucene like queries are not supported in the mus_aq parameter, but if necessary these can be implemented using the mus_sq parameter, which is equivalent to the standard q parameter in solr. If the mus_sq- parameter is given, the query parser is the edismax (extended dismax) query parser.
The result is returned as xml, but can be returned as json by adding &wt=json to the request parameters.
For the sake of readibility, all urls are not escaped in this document. Don't forget to escape the url's in your own code!
Access to the Catch server, hosted by Gemeentemuseum Den Haag is 2 fold:
- IP based access to the server
- API key access to the server (not enforced currently)
Access can be requested by sending a message to ict @ gemeentemuseum .nl
Below, the API definition is given. First an overview of the request format is given followed by the response format. Then MuS specific documentation is given followed by an overview of all supported Solr parameters. The available fields for display and faceting are also covered. At the end some examples are given.
An example of a request is given below: https://catch.kunstmuseum.nl/search?mus_sq=rembrandt&fl=creator
This request performs a simple MuS query and only the field creator is returned in the result list.
The request is a simple GET request to the following URL: https://catch.kunstmuseum.nl/search
followed by MuS specific parameters:
- mus_sq: MuS simple query
- mus_aq: MuS advanced query
- mus_apikey: api key. Without API key only an ID is returned for private records. followed by Solr standard parameters like facet.field, wt and fl.
The response follows the specifications of a standard Solr (3) response. The only available format is xml. Other formats are not supported (yet).
A typical solr response is depicted below:
The doc element contains all (requested) fields of a document unless the document is private in which case only an id is given back. To see all fields for private documents, you need to get a MuS API key.
MuS specific request parameters In the sections below, a detailed explanation of all the MuS specific request parameters is given:
The mus_sq parameter is the simple query parameter. A full-text search through all text fields should be done using this query. The mus_sq parameter is the same as the standard Solr q parameter. The query parser used is the edismax query parser. This cannot be altered.
example: https://catch.kunstmuseum.nl/search?mus_sq=rembrandt nachtwacht
The mus_aq parameter is the advanced query parameter. The query syntax is somewhat different from the mus_sq query syntax: per field of the basic 5 fields a query following the MuS query syntax can be set. The MuS query syntax needs to be surrounded by parentheses. The basic 5 fields are:
- who
- what
- where
- when
- how
The names of these fields are self explaining. So if you want to search for the 'Nachtwacht' not 'selfportret ' by 'Rembrandt', the query per field would be:
what:(Nachtwacht -selfportret)
who:(Rembrandt)
Note that the required (+ or AND) is not supported in field queries because searching in a field implies that the key should match. Therefore required is default behavior.
The full query is done by naming the field, a semicolon and then a valid MuS query surrounded by parentheses, followed by a space and the other field etc. The query to the nachtwacht by Rembrandt would then be:
- https://catch.kunstmuseum.nl/search?mus_aq=who:(rembrandt -selfportret) what:(nachtwacht)
Any other field than the previously mentioned fields will be filtered out without causing an error. If for whatever reason you want to query other fields, use the standard mus_sq parameter. This will be parsed using the edismax query parser of Solr.
The advanced query will also be rewritten to a query in all text fields. The negated keywords (i.e. -Gogh, meaning 'not Gogh'), will be left out. The results stemming from this query will have a low score and can be found below the results of the advanced query.
It might be possible that you want to debug the advanced mus query. This can be done by providing adding debugQuery=true to the query string. In the debug section of the XML the parsed query will be shown. The parsed query is the query that is actually send to Solr. Note that the ranking of the results is done by boost queries. The ranking is already optimized, so there is no possibility to boost the results.
Some documents in the search index are marked private. This means that the supplier of the information has marked some of the content of the document as confidential. In this case, only the id of the document is returned, the rest of the fields is filtered out of the response.
The contents of some private documents can be showed using an api key.
example: https://catch.kunstmuseum.nl/search?mus_sq=rembrandt&mus_apikey=4f8e8f9e7fa36a
The API can be used without apikey.
The Mus query syntax is equal to the dismax query syntax. That is: This is designed to be support raw input strings provided by users with no special escaping. '+' and '-' characters are treated as "mandatory" and "prohibited" modifiers for the subsequent terms. Text wrapped in balanced quote characters '"' are treated as phrases, any query containing an odd number of quote characters is evaluated as if there were no quote characters at all. Wildcards are not supported. A more complex query syntax is not supported and will not be supported in the future.
Because MuS is powered by Solr all the parameters not prefixed by mus_ are just standard Solr parameters which will function as expected. Below are the parameters which will be supported by MuS. MuS is build as a simple query modifier which just passes supported parameters and filters out unsupported ones. The mechanism for this is a blacklist.
More information on these parameters can be found on the Solr wiki pages: http://wiki.apache.org/solr.
This parameter is used to paginate results from a query. When specified, it indicates the maximum number of documents from the complete result set to return to the client for every request. (You can consider it as the maximum number of result appear in the page). The default value is "10".
example:
This parameter is used to paginate results from a query. When specified, it indicates the offset in the complete result set for the queries where the set of returned documents should begin. (i.e. the first record appear in the result set is the offset). The default value is "0".
example:
Sorting by default is on scoring.
"fq" stands for Filter Query. This parameter can be used to specify a query that can be used to restrict the super set of documents that can be returned, without influencing score. It can be very useful for speeding up complex queries since the queries specified with fq are cached independently from the main query. This parameter is mainly used to implement faceted browsing of the results.
example:
This parameter can be used to specify a set of fields to return, limiting the amount of information in the response. When returning the results to the client, only fields in this list will be included. Any field further in the document which is marked as retrievable can be included.
example:
The response writer parameter. Same as in Solr. Use wt=json to get JSON responses instead of XML. note here that the response object can be set to JSON, yet the response content is still XML.
example:
The table below represents all fields that can be used for all different use cases.
| Name | Type | Multiple |
|---|---|---|
| PIDnumber | string | |
| who | fulltext | x |
| what | fulltext | x |
| where | fulltext | x |
| when | fulltext | x |
| how | fulltext | x |
| raw | fulltext | x |
| object_number | string | |
| object_name | fulltext | x |
| creator | fulltext | x |
| production_place | fulltext | x |
| material | fulltext | x |
| technique | fulltext | x |
| title | fulltext | x |
| production_date_start | fulltext | x |
| production_date_end | fulltext | x |
| production_period | fulltext | x |
| inscription_date | fulltext | x |
| inscription_maker | fulltext | x |
| documentation_title | fulltext | x |
| documentation_title_lref | string | x |
| reproduction_reference | string | x |
| part_of_reference | string | x |
| part_of_title | fulltext | x |
| parts_reference | string | x |
| related_object_reference | fulltext | x |
| parts_title | fulltext | x |
| related_object_title | fulltext | x |
|  production_reason |  fulltext | x |
|  edit_date | string |  x |
| institution_name |  fulltext | |
| reproduction_identifier_URL | string | x |
| chronicle_title | fulltext | x |
| chronicle_title_lref | fulltext | x |
| title_short_description | fulltext | |
| creation_presentation | fulltext | |
| production_place_presentation | fulltext | |
| production_date_presentation | fulltext | |
| dimensions_presentation | fulltext | |
| material_technique_presentation | fulltext | |
| credit_line | fulltext | x |
| description_paragraph_presentation | fulltext | x |
| description_qualification_presentation | fulltext | x |
| description | fulltext | x |
| tags | fulltext | x |
| ss_title | fulltext | x |
| alternative_number | string | x |
| alternative_number_type | string | x |
You can query on these fields by passing the fieldname and value separated by a semicolon to the mus_sq query parameter.
example:
To get all the information for a specific result, a detail request can be done. The request format is as follows:
https://catch.kunstmuseum.nl/detail/[PIDnumber]
For a record with PIDnumber 10918x1y59910, the request would be:
Dit is een initiatief van Kunstmuseum Den Haag in het kader van het zgn. Catch Plus project.