Search maps - Fluid Topics - Latest

Fluid Topics API Reference Guide

Category
Reference Guides
Audience
public
Version
Latest

This web service returns maps matching a search query through a paginated response.

The spellcheck option is activated by default. If the query is misspelled, the web service is called again with the new spelling suggested by the spellchecker.

Method Endpoint
POST /api/khub/maps/search
Query parameter Type Required? Description
page Number No Expects the page number. Starts at 1 and defaults to 1.
per_page Number No Expects the number of results per page. Defaults to -1, meaning that all results are returned. The maximum accepted value is 500.
from String No The inclusive start date of the period on which to filter results based on the value of the document's ft:lastTechChange metadata. If unspecified, the default value is 1970-01-01.
to String No The inclusive end date of the period. The inclusive start date of the period. If unspecified, the default value is the current day.
  • It is possible to use pagination with this web service.
  • Using pagination when searching maps is recommended.
  • It is possible to paginate this web service using either query parameters or fields in the request body. If both methods are used, the values of the query parameters take precedence.
  • It is possible to specify a period for this web service using either query parameters or fields in the request body. If both methods are used, the values of the query parameters take precedence.
  • When no user credentials are provided in the HTTP header, this web service only returns public results.

As a USER_ADMIN user, it is possible to impersonate another user when using this web service.

Return code Description
200 OK The request is valid and data is returned.
400 BAD REQUEST The JSON request body is invalid.
500 INTERNAL SERVER ERROR The Query Manager failed to respond.

Request example

The following lines show an example of a JSON request body:

{
  "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
    },
    ...
  ],
  "lastModified": {
    "from": "2022-01-01",
    "to": "2022-09-30"
  },
  "paging": {
    "page": 1,
    "perPage": 20
  }
}
Field Type Required? Description
query String No Expects the string query used to return matching publications. If not set, results are based on other parameters such as contentLocale and filters.
contentLocale String Yes Expects the content language's ISO code.
uiLocale String No Expects the interface language's ISO code. If undefined, Fluid Topics tries to detect the interface language and uses it to return facets in the correct language.
filters Array No Filters the results based on selected criteria. Defaults to an empty list.
    key String Yes Expects a metadata key.
    values Array Yes Defines the value for the selected key. When multiple values are defined, they are combined with an AND or an OR operator depending on the tenant's configuration.
    negative Boolean No When set to true, the results matching the previously defined values are excluded. By default, the negative parameter is implicit and set to false.
sort Array No Makes it possible to specify a custom sort based on any available metadata key and value pair.
    key String Yes Expects a metadata key by which to sort results, for example, ft:lastPublication, ft:topicTitle, or ft:relevance.
    order String Yes Expects either ascending (ASC) or descending (DESC). By default, the standard Fluid Topics sort order applied.
facets Array No Displays facets that can be used to filter results. Facets are displayed in the same order as they are declared. The facets parameter can be absent. It can also be present but empty.
    id String Yes The facet's unique identifier.
    maxDepth Number Yes Defines the maximum depth level for the facet. When displaying a hierarchical facet, the entire hierarchy is displayed by default.
lastModified Object No Restricts results to those with a value for the ft:lastTechChange metadata that is within the specified period.
    from String Yes The inclusive start date of the period. If unspecified, the default value is 1970-01-01.
    to String Yes The inclusive end date of the period. If unspecified, the default value is the current day.
paging Object No Expects information about pagination. By default, pagination is set to page 1 with 20 results per page.
    page Number Yes The number of the page to display among those containing results for the query.
    perPage Number Yes The number of results to display for each page.

Response body

The following lines show an example of a JSON response body:

{
    "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"
            ]
          }
        ]
      }
    ],
    "lastModified": {
      "from": "2022-01-01",
      "to": "2022-09-30"
    },
    "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 an abstract as displayed in the Search page, written in HTML with kwicstring and kwicmatch CSS classes. This field remains empty for books.