Product Selector

Fusion 5.9
    Fusion 5.9

    SearchSpringboard Query API

    The search endpoint of the Query API searches an indexed collection of data for relevant full-term matches to user-specified search terms. It powers the search feature in your search application.

    Send your requests to the search endpoint using POST to create a query and receive a response.

    Prerequisites

    Before using this endpoint, use the Authentication API with the scope value of connectedsearch.query to generate an access token. The access token is used to authenticate your requests.

    You must also supply the APPLICATION_ID value, as the request URL requires it. To obtain the value, click the Integrations icon from the Applications UI sidebar and then click the APIs tab. The value is in the Application ID field.

    Basic search request

    A basic search request requires three fields and values: query, utcOffset, and sessionId.

    Key Description

    query

    The search string.

    utcOffset

    The difference between Coordinated Universal Time (UTC) and your time zone, formatted with six characters as ±00:00.

    sessionId

    Unique value that identifies the user’s session. Consider passing the session ID value from your user’s browser session as the value of sessionId. For more information, see the MDN developer documentation for sessionStorage.

    The following example displays a minimal search cURL request.

    Replace APPLICATION_ID with your Application ID. Replace ACCESS_TOKEN with the access token you generated using the Authentication API.

    curl --request POST \
      --url https://APPLICATION_ID.applications.lucidworks.com/query/search \
      --header 'Authorization: Bearer ACCESS_TOKEN' \
      --header 'Content-Type: application/json' \
      --data '{
      "query": "Star Wars",
      "utcOffset": "-05:00",
      "sessionId": "864782f0-af36-4dee-8430-9e73d6006eaa"
    }'

    The minimum response for the searched term or phrase includes a count of all possible matches as hits.

    {
      "queryId" : "fd110486-f168-47c0-a419-1518a4840589",
      "hits" : 4,
      "docs" : [ {
        "type" : "page",
        "id" : "441eb3be-7de6-470a-8141-e416a15c7db1-6a092bd4-5098-466c-94aa-40bf68294303-68708807657148371333355819934570439731",
        "rank" : 57,
        "datasourceLabels" : [ "movies" ],
        "fields" : {
          "document.title" : "Star Wars",
          "document.url" : "https://example.com/docs/movies/257.html"
        }
      }, {
        "type" : "page",
        "id" : "441eb3be-7de6-470a-8141-e416a15c7db1-fb148491-b39e-46d1-af33-44cd964d8ee0-34049685392290835527739651484332150529",
        "rank" : 8,
        "datasourceLabels" : [ "books" ],
        "fields" : {
          "document.title" : "Rebel power! / written by Lauren Nesworthy.",
          "document.url" : "https://example.com/docs/seattle-books/3077219.html"
        }
      }, {
        "type" : "page",
        "id" : "441eb3be-7de6-470a-8141-e416a15c7db1-118109e5-7ec5-42bb-834d-e3cd41bba65f-47402309926353658638499384569395150502",
        "rank" : 5,
        "datasourceLabels" : [ "movies" ],
        "fields" : {
          "document.title" : "Return of the Jedi",
          "document.url" : "https://example.com/docs/movies/1168.html"
        }
      }, {
        "type" : "page",
        "id" : "441eb3be-7de6-470a-8141-e416a15c7db1-d439fd0d-1edf-4982-b00c-51c94a5c0490-43870931094300738494010378876873965115",
        "rank" : 5,
        "datasourceLabels" : [ "movies" ],
        "fields" : {
          "document.title" : "The Empire Strikes Back",
          "document.url" : "https://example.com/docs/movies/1155.html"
        }
      } ]
    }

    The second item in the preceding response is a page with a link to the first item, which is why the information returned does not initially appear to match the query.

    Advanced search request

    The following request includes all possible fields.

    curl --request POST \
      --url https://APPLICATION_ID.applications.lucidworks.com/query/search \
      --header 'Authorization: Bearer ACCESS_TOKEN' \
      --header 'Content-Type: application/json' \
      --data '{
      "query": "Star Wars",
      "page": 0,
      "limit": 1,
      "utcOffset": "-05:00",
      "sessionId": "864782f0-af36-4dee-8430-9e73d6006eaa",
       "sort": [
       {"sortField": "relevancy", "sortOrder": "asc"}
      ],
      "fieldList": ["document.title", "document.url"],
        "facets": ["type", "file.extension", "document.languageCode"],
        "highlight": false,
        "filters": [
        {"field": "document.languageCode", "values": ["en"]},
        {"field": "datasourceLabels", "values": ["movies"]}
      ],
      "analyticsData": true
    }'

    The following sample displays the full response.

    {
      "queryId" : "fd110486-f168-47c0-a419-1518a4840589",
      "hits" : 3,
      "docs" : [ {
        "type" : "page",
        "id" : "441eb3be-7de6-470a-8141-e416a15c7db1-6a092bd4-5098-466c-94aa-40bf68294303-68708807657148371333355819934570439731",
        "rank" : 57,
        "datasourceLabels" : [ "movies" ],
        "fields" : {
          "document.title" : "Star Wars",
          "document.url" : "https://example.com/docs/movies/257.html"
        }
      } ],
      "facets" : {
        "field" : {
          "file.extension" : {
            "missing" : 3,
            "counts" : [ ]
          },
          "type" : {
            "missing" : 0,
            "counts" : [ {
              "name" : "page",
              "count" : 3
            } ]
          },
          "document.languageCode" : {
            "missing" : 0,
            "counts" : [ {
              "name" : "en",
              "count" : 3
            } ]
          }
        }
      }
    }

    Notice the request had three hits, but only one record was returned. This happened because the number of responses in the request was listed as 1 maximum using "page": 0, "limit": 1.

    Page display

    Use the page and limit values to paginate your results. Using the default values, "page": 0, "limit": 20 means you start with the first page and display results 1 through 20. If you change the values to "page": 1, "limit": 20, the request returns the second page with query matches 21 through 40.

    When building the search experience for your application or website, you can use hits to calculate the total number of pages before zero results are shown as Pages ≤ hits/limit.

    If you do not specify page and limit in your request, the API assumes the default values and returns the first page with 20 results.

    Change response sort order

    The default for sorting when a response is returned is by highest to lowest ranks, meaning the match strength for that particular query.

    To sort in a different way, include sort in your request. For example, "sort": [{"sortField": "relevancy", "sortOrder": "asc"}] sorts the response by lowest to highest ranks.

    Highlight query terms

    Use "highlight": true to add HTML emphasis tags (<em>) around words matching your search.

    The following sample shows how the highlighted emphasis tags are applied.

    {
        "queryId": "fd110486-f168-47c0-a419-1518a4840589",
        "hits": 2,
        "docs": [
            {
                "type": "Page",
                "id": "441eb3be-7de6-470a-8141-e416a15c7db1-6a092bd4-5098-466c-94aa-40bf68294303-68708807657148371333355819934570439731",
                "rank": 81,
                "datasourceLabels": [
                    "game"
                ],
                "fields": {
                    "document.title": "<em>Babbling</em> <em>Book</em>",
                    "document.url": "https://example.com/docs/seattle-books/KAR_009.html"
                }
            }
        ]
    }

    Return only specified fields

    Use fieldList to only return the fields that you specify. For example, to see a document’s title in the response but not the URL or other fields, use "fieldList": ["document.title"].

    Filter using facets

    Include facets in your request to return a count of documents containing that facet. This count appears at the end of the response after the documents.

    For example, to show a count of documents containing the type, file.extension, and document.languageCode facets, include "facets": ["type", "file.extension", "document.languageCode"] in your request.

    A sample response follows. The docs section is omitted for clarity.

    {
        "queryId": "fd110486-f168-47c0-a419-1518a4840589",
        "hits": 2,
        "docs": [
            ...
        ],
        "facets": {
            "field": {
                "file.extension": {
                    "missing": 2,
                    "counts": []
                },
                "type": {
                    "missing": 0,
                    "counts": [
                        {
                            "name": "Page",
                            "count": 2
                        }
                    ]
                },
                "document.languageCode": {
                    "missing": 0,
                    "counts": [
                        {
                            "name": "en",
                            "count": 2
                        }
                    ]
                }
            }
        }
    }

    Filter using fields

    Include filters in your request to limit the results to specific field values. For example, to include only documents written in English, include "filters": [{"field": "document.languageCode", "values": ["en"]}] in your request.

    Analytics data

    By default, analyticsData is set to true and the request is included in analytical data. If you are testing a request and do not want it to appear in your analytical data, use "analyticsData": false.

    Special characters

    Character escaping in JSON requests to the search endpoint is handled using a backslash, \. If a query includes a backslash or double quotes, you must escape these or the JSON request is considered invalid.

    This table lists which special characters can be escaped in a request.

    Escape Sequence Resulting Character

    \\

    \

    \"

    "

    \b

    backspace

    \t

    tab

    \n

    newline

    \f

    form feed

    \r

    carriage return

    A backslash followed by any other character returns an invalid JSON error message. Unicode character sequences are not accepted. Instead they are passed as literal values.