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 |
|---|---|
|
The search string. |
|
The difference between Coordinated Universal Time (UTC) and your time zone, formatted with six characters as |
|
Unique value that identifies the user’s session. Consider passing the session ID value from your user’s browser session as the value of |
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 |
|---|---|
|
|
|
|
|
backspace |
|
tab |
|
newline |
|
form feed |
|
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.