Search API
Get search results data in JSON.
Prerequisites
Ensure that you have fulfilled the prerequisites before making your first call.
1. Set a user scope
SearchUnify users can have one of these five scopes. Each scope has an impact on the calls a user can make. The instructions to change user scope are in Change User Scope.
2. Create an app
At the time of creating an app, you obtain a client ID and client secret. Both are used to ascertain your identity. The process of creating an app has been explained in Get Client ID and Client Secret with an API App.
3. Obtain access and refresh tokens using the app
Access and a refresh tokens are required to be able to use the search API. The process of generating these tokens has been explained in Get Access and Refresh Token Using curl.
Using Access and Refresh Tokens
The token generation call produces two kinds of tokens: Refresh and Access.
The refresh token expires every 14 days. Store it securely. The sole use of refresh tokens is to generate access tokens.
Access tokens expire every four hours. They authenticate users. It is mandatory to include them in the header of your API calls. The format is -H "authorization: Bearer {{access token}}"
.
Base URL
https://{{hostname}}/api/v2_search/The hostname is the URL of your SearchUnify instance.
Example Base URL
https://mycompany.searchunify.com/api/v2_search/Endpoints
POST /searchResults
View search results on a platform of your choice.
Parameters
| Parameter | Optional / Required | Description | Data Type |
|---|---|---|---|
uid
|
Required | It is your search client ID. You can find it in Search Clients > UID (column). | string |
searchString
|
Required | It is the search query. | string |
email
|
Optional | This parameter is used establish the searcher's identity and tailor search results based on that identity. An admin email might fetch results different from a moderator email. | string |
orderBy
|
Optional | It has two values, asc and desc. If orderby=desc, then the order in which the results are presented is reversed. The last result will be ranked first, the penultimate result second, and so on. The default value of orderBy is asc. |
string |
sortby
|
Optional | It can have two values, _score or post_time. When sortby=_score, then the documents with the highest score are presented first. When sortby=post_time, then the lastest documents are on top. |
string |
exactPhrase
|
Optional | It treats all the words in the search query as one contiguous string. exactPhrase=salesforce console becomes "salesforce console". |
string |
withOneOrMore
|
Optional | When used, it inserts the Boolean operator OR between each pair of keywords. withOneOrMore=salesforce console becomes "salesforce OR console". |
string |
withoutTheWords
|
Optional | This parameter inserts the Boolean operator NOT before each keyword. withoutTheWords=salesforce console becomes "NOT salesforce NOT console" |
string |
from
|
Optional | It's an offset. If from="10", then the call will ignore the top 10 results and fetch results starting from the document ranked 11. |
string |
resultsPerPage
|
Optional | If resultsPerPage=30, then each search will produce 30 results on each page. |
string |
indexEnabled
|
Optional | The content sources tabs are hidden if indexEnabled is set to false. In the default state, indexEnabled=true. |
boolean |
aggregations
|
Optional | aggregations is used to refine your search with facets. For example: type: ${facet name}, filter: [ ${facet filter name1}, ${facet filter name2} ]. A common pattern for nested facets is [{type: ${facet name},children: [ childname: ${facet child name1}, level: ${facet level} ]}] |
object |
pagingAggregation
|
Optional | It is used if your goal is to display all your facets. {key: ${facet name},keyword: ${facet search keyword},offset: ${number of filters to shown}} |
object |
pageNo
|
Optional | Returns search results from the specified page number. If pageNo==5, then the results from the fifth page will be returned. |
|
sid
|
Optional | Attaches session ID(s) to the returned data. | |
language
|
Optional | Returns results in the specified language. language=zh returns Chinese results. |
|
versionResults
|
Optional | Merge multiple versions of a doc into a result. | |
getAutoTunedResult
|
Optional | Returns auto tuned results. Works only if Auto Spell Corrector and Facet Interpretor are enabled in the instance. | |
getSimilarSearches
|
Optional | Returns results from the similar searches tab. Works only if Similar Searches is turned on in the instance. | |
mergeSources
|
Optional | Groups results by content sources. Works only if Customize Search Client View is turned on in the instance. |
Salesforce-Specific Parameters
| Parameter | Optional / Required | Description | Data Type |
|---|---|---|---|
UserId
|
Optional | Your user ID. | string |
UserType
|
Optional | Your user type. For example, Standard, Admin, and Developer. | string |
AccountId
|
Optional | Your Salesforce ID. | string |
ProfileId
|
Optional | Your profile ID in your org. | string |
ContactId
|
Optional | Your contact ID. | string |
Lithium-Specific Parameters
| Parameter | Optional / Required | Description | Data Type |
|---|---|---|---|
boardsArr
|
Required | It limits search to the boards specified in boardsArr. |
string |
Example Request
curl -X POST 'https://grazitti.searchunify.com/dev/api/v2_search/searchResults'
-H 'Content-Type: application/json' -H "authorization: Bearer ACCESS_TOKEN"
--data-binary $'
{
\n"uid":"SEARCH_CLIENT_ID",
\n"searchString":"salesforce",
\n"sortby":"_post_time",
\n"resultsPerPage":"20" \n
}'