Search Maps - Fluid Topics - 3.6

Use Fluid Topics Web API

Product
Fluid Topics
FT_Version
3.6
Category
Technical Notes
language
English

This web service is used to search maps. It returns unclustered maps matching the query conditions through a paginated output.

The spellcheck option is activated by default. If the query is misspelled, the request is launched again with the new spelling suggested by the spellchecker.

Facets can be added for users to filter the matching publications.

Method

Endpoint

POST

/api/khub/maps/search

Return codes

Return Code

Description

200 OK

Returns 0 or more results.

400 BAD REQUEST

Invalid JSON input.

500 INTERNAL SERVER ERROR

The Query Manager failed to respond.

The request must set the Content-Type: application/json header.

Input Template

The input JSON expects the following parameters:

Parameter

Cardinality

Type

Description

query

Optional

String

Expects the string query used to return matching publications. If not set, an empty search is queried.

contentLocale

Mandatory

String

Expects the content language ISO code. If not set, the query fails.

uiLocale

Optional

String

Expects the UI language ISO code. If not set, Fluid Topics tries to detect the user locale. This locale is used to return facet labels in the correct language, for instance.

filters

Optional

filter Array

Enables to filter the results on some metadata values.

The filter object expects the following criteria:

  • key (mandatory): Filter keys can be any user metadata or technical facets.
  • values (mandatory): Defines the value for the given key. When multiple values are given, they are combined with an AND or an OR operator depending on the tenant configuration.
  • negative (optional): When set to true, the results matching the previously set values are excluded. By default, the negative parameter is implicit and set to false.

Defaults to empty list.

sort

Optional

sort Object

Enables to specify a custom sort on any metadata.

The sort object expects the following criteria:

  • key (mandatory): Sort criterion keys can be any user metadata or technical facets, for example:
    • ft:lastPublication
    • ft:topicTitle
    • ft:relevance is a special keyword is provided to sort by relevance.
  • order (mandatory): Each criterion can be ascendant (ASC) or descendant (DESC). By default, the standard Fluid Topics sort order is used.

facets

Optional

facet Array

Enables to display facets from their facet ID. Users can then filter content through these facets.

Facets are displayed in the same order as they are declared.

If facets is absent or present but empty, no facet is displayed.

The facet object expects the following criteria:

  • id (mandatory): Is the facet ID.
  • maxDepth (optional): Defines the maximum depth level for the facet. When displaying a hierarchical facet, by default, the whole hierarchy is displayed.

paging

Optional

paging Object

Expects the following paging information:

  • page (mandatory): Is the number of the queried result page.
  • perPage (optional): Is the number of result clusters for each page.

By default, the pagination is set to page 1 and 20 results per page.

The following lines display an example of JSON input:

{
"query": "$KEYWORDS",
"contentLocale": "$LOCALE",
"filters": [
{
"key": "$FACET_ID_1",
"values": ["$FACET_VALUE_A", "$FACET_VALUE_B"]
},
{
"key": "$FACET_ID_2",
"values": ["$FACET_VALUE_C"]
}
],
"sort": [
{
"key": "$FACET_ID_1",
"order": "ASC"
},
{
"key": "$FACET_ID_2",
"order": "DESC"
}
],
"facets": [
{
"id": "$FACET_ID_1",
"maxDepth": 2
},
...
],
"paging": {
"page": 1,
"perPage": 20
}
}

Output Example

{
"spellcheck": {
"suggestedQuery": "correctedKeywords",
"htmlSuggestedQuery": "<span class=\"kwicmatch\">correctedKeywords</span>"
},
"facets": [
{
"key": "ft:isPublication",
"label": "ft:isPublication",
"hierarchical": false,
"multiSelectionable": true,
"rootNodes": [
{
"value": "true",
"label": "true",
"selected": false,
"totalResultsCount": 1,
"childNodes": [],
"descendantSelected": false
}
]
}
],
"results": [
{
"mapId": "qT_JLCMeNICKqt7tLEWRdg",
"mapUrl": "http://mysite.net/api/khub/maps/qT_JLCMeNICKqt7tLEWRdg",
"title": "Fluid Topics map Bar",
"htmlTitle": "<span class=\"kwicmatch\">Fluid</span><span class=\"kwicstring\"> Topics map Bar</span>",
"htmlExcerpt": "",
"metadata": [
{
"key": "product",
"label": "Product",
"values": [
"FT"
]
},
{
"key": "version",
"label": "Version",
"values": [
"3.0"
]
}
]
},
{
"mapId": "HFlZxzdmBKezTw9roSRsrA",
"mapUrl": "http://mysite.net/api/khub/maps/HFlZxzdmBKezTw9roSRsrA",
"title": "Fluid Topics map Foo",
"htmlTitle": "<span class=\"kwicmatch\">Fluid</span><span class=\"kwicstring\"> Topics map Foo</span>",
"metadata": [
{
"key": "product",
"label": "Product",
"values": [
"FT"
]
},
{
"key": "version",
"label": "Version",
"values": [
"3.1"
]
}
]
}
],
"paging": {
"currentPage": 1,
"totalResultsCount": 2,
"isLastPage": true
}
}

Where:

  • kwicstring is the part of the original query which was correctly spelled.
  • kwicmatch is the part of the query corrected by the spellchecker.
  • htmlExcerpt corresponds to the Article excerpt as displayed in the Search Results page, written in HTML with kwicstring and kwicmatch CSS classes. This field remains empty for Books as they do not have abstracts in the Search Results page.