Search maps - Fluid Topics

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

The spellcheck option is activated by default. If the query contains a misspelling, 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`, which returns all results. 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 returns data.
`400 BAD REQUEST`	The JSON request body is invalid.

Request example

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

The word "API" is deliberately misspelled as "APPI" as the value for the query field.

{
  "query": "APPI",
  "contentLocale": "en-US",
  "metadataFilters": [
    {
      "key": "version",
      "valueFilter": {
        "values": ["1.1", "1.2"],
        "negative": false
      }
    },
    {
      "key": "category",
      "valueFilter": {
        "values": ["Reference Guides"],
        "negative": false
      }
    }
  ],
  "sort": [
    {
      "key": "ft:lastPublication",
      "order": "DESC"
    }
  ],
  "facets": [
    {
      "id": "author",
      "maxDepth": 1
    }
  ],
  "lastModified": {
    "from": "2024-01-01",
    "to": "2024-04-09"
  },
  "paging": {
    "page": 1,
    "perPage": 20
  }
}

Field	Type	Required?	Description
`query`	String	No	Expects the string query used to return matching publications. If not set, other parameters such as `contentLocale` and `metadataFilters` determine the results.
`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.
`metadataFilters`	Array	No	Filters the results based on selected criteria including metadata and date ranges. Defaults to an empty list.
`key`	String	Yes	Expects a metadata key.
`valueFilter`	Object	No	Contains the filtering conditions based on metadata values.
`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`, this parameter excludes results matching the previously defined values. By default, the `negative` parameter is implicit and set to `false`.
`dateFilter`	Object	No	Specifies the date-based filtering conditions using predefined periods.
`type`	String	Yes	Restricts results to those within a predefined period. Acceptable values are `LAST_WEEK`, `LAST_MONTH`, `LAST_QUARTER`, `LAST_YEAR`.
`rangeFilter`	Object	No	Specifies custom date range filtering.
`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.
`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 is applied.
`facets`	Array	No	Displays facets that can be used to filter results. Facets appear in the same order as 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. By default, `maxDepth` has a value of `8`.
`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": "API",
        "htmlSuggestedQuery": "<span class=\"kwicmatch\">API</span>"
    },
    "facets": [
        {
            "key": "ft:isPublication",
            "label": "ft:isPublication",
            "hierarchical": false,
            "multiSelectionable": true,
            "rootNodes": [
                {
                    "value": "John Doe",
                    "label": "John Doe",
                    "selected": false,
                    "totalResultsCount": 19,
                    "childNodes": [],
                    "descendantSelected": false
                },
                {
                    "value": "Paul Dupont",
                    "label": "Paul Dupont",
                    "selected": false,
                    "totalResultsCount": 8,
                    "childNodes": [],
                    "descendantSelected": false
                }
            ]
        }
    ],
    "results": [
      {
        "mapId": "qT_JLCMeNICKqt7tLEWRdg",
        "mapUrl": "http://my_site.fluidtopics.net/api/khub/maps/qT_JLCMeNICKqt7tLEWRdg",
        "title": "API Reference Guide",
        "htmlTitle": "<span class=\"kwicstring\">Fluid Topics </span><span class=\"kwicmatch\">API</span><span class=\"kwicstring\"> Reference Guide</span>",
        "htmlExcerpt": "",
        "metadata": [
          {
            "key": "product",
            "label": "Product",
            "values": [
              "FT"
            ]
          },
          {
            "key": "category",
            "label": "Category",
            "values": [
              "Reference Guides"
            ]
          },
          {
            "key": "version",
            "label": "Version",
            "values": [
              "1.1"
            ]
          }
        ]
      },
      {
        "mapId": "HFlZxzdmBKezTw9roSRsrA",
        "mapUrl": "http://my_site.fluidtopics.net/api/khub/maps/HFlZxzdmBKezTw9roSRsrA",
        "title": "Cluster Documents and Topics",
        "htmlTitle": "<span class=\"kwicstring\">Cluster Documents and Topics</span>",
        "htmlExcerpt": "<span class=\"kwictruncate\">...</span><span class=\"kwicstring\">Word Paligo Use the </span><span class=\"kwicmatch\">web service</span><span class=\"kwicstring\"> to update ft:clusterId</span><span class=\"kwictruncate\">...</span><span class=\"kwicstring\">or replace metadata with the </span><span class=\"kwicmatch\">web service</span><span class=\"kwicstring\">. It is possible to</span><span class=\"kwictruncate\">...</span><span class=\"kwicstring\">originId . Use an existing </span><span class=\"kwicmatch\">API</span><span class=\"kwicstring\"> key with the appropriate access and editing rights (KHUB_ADMIN or CONTENT_PUBLISHER) Use the method PUT as well as this endpoint /</span><span class=\"kwicmatch\">api</span><span class=\"kwicstring\">/admin/khub/</span><span class=\"kwictruncate\">...</span>",
        "metadata": [
          {
            "key": "category",
            "label": "Category",
            "values": [
              "Reference Guides"
            ]
          },
          {
            "key": "version",
            "label": "Version",
            "values": [
              "1.0"
            ]
          }
        ]
      }
    ],
    "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.

Search maps - Fluid Topics - Latest

Fluid Topics API Reference Guide