Open Suggestion Service

Versions

URLData repository versionEnvironmentWSDL
http://opensuggestion.addi.dk/b3.5_2.0/3.5productionWSDL
http://opensuggestion.addi.dk/staging_2.0/3.5stagingWSDL

Introduction

The Suggestion Service returns auto completion suggestions from the Solr-index of the Data Well that can be used for later searches.

The scanterm- and scanphrase-indexes of the Open Search data well are designed to be used with the Suggestion Service.

The service currently has four operations:

REST interface supports XML or JSON formatted output controlled through the "Accept" HTTP header. Use either "application/xml" or "application/json".

The facets, facetspell and spellcheck requests are also available through SOAP

Also check out the SOAP and REST example pages.

Terms

Accessible through /rest/terms path on the service.

Retrieve suggestions based on the Solr TermsComponent, including frequency data of how often words or phrases (depending on index type) occur in the specified index, which indicates how many objects in the Data Well that match the query.

For term indexes the query string can only contain one term and the response will contain only single words.

For Phrase index you can query for multiple words and it will respond with entire phrases, but only phrases that begin with the requested query. It can not find phrases that otherwise contain the words of the query

Required parameters:

queryThe string to find suggestions for
indexThe index to find suggestions in

Optional parameters:

lowerTerm to continue from when asking for next available suggestions. Response will continue suggestions from the next term after this term. Only usable when specifying index sort order

Examples

http://oss-services.dbc.dk/suggest/rest/terms?query=goblet&index=scanterm.title
http://oss-services.dbc.dk/suggest/rest/terms?query=harry+potter&index=scanphrase.title

Facets

Accessible through /rest/facets path on the service or SOAP at SuggestionService endpoint.

Retrieve suggestions based on the Solr Facets, including frequency data of how often words or phrases occur in the specified index, which indicates how many objects in the Data Well that matches each of the returned facets.

This variant looks in the specified index for entries that contain the words from specified query string and then counts results in groups based on the specified facet index. This will also provide suggestions for phrases that contain the words from the query string.

Care should be taken in selecting a suitable pair of indexes. The match index should be a term index where phrases like titles and names are broken down into individual words. This allows finding the requested words in any order and allows the query to be an incomplete phrase. The facetIndex should be a phrase index where the entire title or name is stored and available for output. The facet index should be an index generated from the same data (e.g. titles or author names) as the match index. If the chosen facet index contain a different type of data than the match index, the returned suggestions may not contain useful data.

Required parameters:

queryThe word or words to find suggestions for
indexThe index to find word matches in
facetIndexThe index to get suggestions from

Optional parameters:

offsetOffset to continue from when asking for next available suggestions. Default is 0
sortSort method to use. Count sorts after facet frequency, and index uses the default sort method of the specified facetIndex (usually alphabetical). (count|index. Default is count)

Examples

http://oss-services.dbc.dk/suggest/rest/facets?query=goblet+fire&index=scanterm.mainTitle&facetIndex=scanphrase.mainTitle

 

FacetSpell

 

Accessible through /rest/facetSpell path on the service or SOAP at SuggestionService endpoint.

This operation is similar to Facets, as it uses Solr faceting to generate suggestions. The main difference is that FacetSpell is less likely to return an empty suggestion list, since the query words undergo spell checking. The query words will be checked against the SpellCheck service and alternate spelling of words contribute to the search for matches in the index.

Another difference from the facets operation is how suggestions are ranked. Instead of only using frequency, three measures are used for calculating the score. The weight of each may be tuned with the parameters rankWeight, frequencyWeight, and similarityWeight.

A consequence of using alternate spelling of words, is that the user is interested in only a few of the alternate words, and hence noise creeps into the suggestions. The similarity score resembles how similar a suggestion is to the user provided query, and thereby moves noise down the list. The frequency score is based on the facet frequency. The rank score is based on how popular each word of the suggestion is. A word is popular if it occurs frequently in search requests.

A thing to note is that the ranking is done outside Solr, in the service, and hence is only done on the subset of facet suggestions returned by Solr. This means that increasing maxSuggestions may change the order of the suggestions, if a suggestion has low frequency, but high similarity and/or popularity.

Required parameters:

queryThe word or words to find suggestions for
indexThe index to find word matches in
facetIndexThe index to get suggestions from

Optional parameters:

cursorPosLocation of the cursor or caret in the user interface input field. Can be used when the user goes back and edits existing text. Will insert wildcard search at the cursor location to give suggestions to the text being edited. Default assumes cursor at end of query
debugInclude debug information in the response. true/false. Default is false
rankWeightThe weight of the rank score (popularity score). Default 1
frequencyWeightThe weight of the frequency score. Default 1
similarityWeightThe weight of the similarity score. Default 3

Common optional parameters for Terms, Facets and FacetSpell

filterQueryA query that may be used to filter the area you want to get suggestions from
agencyOnly get suggestions from data accessible to the specified agency
profileOnly get suggestions from data accessible to the specified search profile
highlightProduce highlight tags to mark the substrings that match the query. (true/false, default is false)
highlight.preSet highlight prefix tag to use if highlighting is enabled (default is <em>)
highlight.postSet highlight postfix tag to use if highlighting is enabled (default is </em>)
maxSuggestionsMaximum number of suggestions to return. (default is 10)
maxTimeWhen filtering suggestions with filterQuery, agency and/or profile, stop looking for suggestions after this number of milliseconds. Used to avoid waiting a long time when an index has many matches for the query but not many for the filter (default is 2000)

SpellCheck

Accessible through /rest/spell path on the service or SOAP at SuggestionService endpoint.

This operation takes a phrase as input and returns a list of spell suggestions for each word. Each suggestion is associated with a weight between zero and one, specifying its quality.

Required parameter:

phraseThe word or words to find suggestions for

Optional parameter:

maxSuggestionsMaximum number of suggestions to return. (default is 10)