Python SDKs
The Python SDK can be used to fetch analytics data, render search results, and obtain information on content source data.
Prerequisite
Install python 3.0 or higher.
Ensure that your profile is in the right scope. Refer to Change User Scope (API and SDK).
Initialization
Before using SDK you must have to initialize first. In this process you just need to ensure authentication. We have two methods to generate and refresh access tokens. After initializing SDK you can access SearchUnify analytics, content and search.
Initialize Python SDK
from searchunify import startClient, refreshToken
username = "**************"
password = "**************"
clientId = "**************"
secrets = "**************"
url= "yourcompany.searchunify.com"
result = startClient(username=username, password=password,clientId=clientId, secrets=secrets, instance=url)
The access token expires every four hours. You can refresh it with the refreshToken() function.
Generate refresh token
from searchunify import startClient, refreshToken
result = refreshToken()
Analytics
To access analytics data you can use analytics functions. There are around 22 methods for various use cases.
Returns data on visitors, search users, clicks, results, cases, and other essential search behavior.
Parameters
Parameter | Optional / Required | Type |
startDate | Required | String |
endDate | Required | String |
searchClientId | Optional | String |
Example Request
getTilesData()
from searchunify import *
startDate = "2021-05-25"
endDate = "2021-06-01"
searchClientId = "5815771e-69dc-11eb-94cc-0242ac120007"
data = getTilesData(startDate=startDate, endDate=endDate, searchClientId=searchClientId)
print("The tile data ", data)
Returns how All Searches, All Searches with Results, and All Searches with Clicks (conversions) have changed over the period between startDate and endDate.
Parameters
Parameter | Optional / Required | Type |
startDate | Required | String |
endDate | Required | String |
searchClientId | Optional | String |
Example Request
getSearchSummaryChart()
from searchunify import *
startDate = "2021-05-25"
endDate = "2021-06-01"
searchClientId = "5815771e-69dc-11eb-94cc-0242ac120007"
data = getSearchSummaryChart(startDate=startDate, endDate=endDate, searchClientId=searchClientId)
print("The getSearchSummaryChart data ", data)
Returns the most popular search queries.
Parameters
Parameter | Optional / Required | Type |
startDate | Required | String |
endDate | Required | String |
searchClientId | Optional | String |
count | Required | Integer |
Example Request
getAllSearchQuery
from searchunify import *
startDate = "2021-06-01"
endDate = "2021-06-04"
count = 5
searchClientId = "5815771e-69dc-11eb-94cc-0242ac120007"
result = getAllSearchQuery(startDate=startDate, endDate=endDate,count=count, searchClientId=searchClientId)
print("The getAllSearchQuery data ", result)
Returns the most popular search queries for which results were found.
Parameters
Parameter | Optional / Required | Type |
startDate | Required | String |
endDate | Required | String |
searchClientId | Optional | String |
count | Required | Integer |
Example Request
searchQueryWithResult
from searchunify import *
startDate = "2021-06-01"
endDate = "2021-06-04"
count = 5
searchClientId = "5815771e-69dc-11eb-94cc-0242ac120007"
result = searchQueryWithResult(startDate=startDate, endDate=endDate,count=count, searchClientId=searchClientId)
print("The searchQueryWithResult data ", result)
Returns the most popular search queries for which results were found but users didn't click on any of them.
Parameters
Parameter | Optional / Required | Type |
startDate | Required | String |
endDate | Required | String |
searchClientId | Optional | String |
count | Required | Integer |
Example Request
searchQueryWithNoClicks
from searchunify import *
startDate = "2021-06-01"
endDate = "2021-06-04"
count = 5
searchClientId = "5815771e-69dc-11eb-94cc-0242ac120007"
result = searchQueryWithNoClicks(startDate=startDate, endDate=endDate,count=count, searchClientId=searchClientId)
print("The searchQueryWithNoClicks data ", result)
Returns the most popular search queries for which no results were found.
Parameters
Parameter | Optional / Required | Type |
startDate | Required | String |
endDate | Required | String |
searchClientId | Optional | String |
count | Required | Integer |
Example Request
searchQueryWithoutResults
from searchunify import *
startDate = "2021-06-01"
endDate = "2021-06-04"
count = 5
searchClientId = "5815771e-69dc-11eb-94cc-0242ac120007"
result = searchQueryWithoutResults(startDate=startDate, endDate=endDate,count=count, searchClientId=searchClientId)
print("The searchQueryWithoutResults data ", result)
Returns search and conversion data over the period between startDate and endDate.
Parameters
Parameter | Optional / Required | Type |
startDate | Required | String |
endDate | Required | String |
searchClientId | Optional | String |
count | Required | Integer |
Example Request
searchQueryHistogram
from searchunify import *
startDate = "2021-06-01"
endDate = "2021-06-04"
count = 5
searchClientId = "5815771e-69dc-11eb-94cc-0242ac120007"
result = searchQueryHistogram(startDate=startDate, endDate=endDate,count=count, searchClientId=searchClientId)
print("The searchQueryHistogram data ", result)
Returns the total number of queries that didn't produce even one result.
Parameters
Parameter | Optional / Required | Type |
startDate | Required | String |
endDate | Required | String |
searchClientId | Optional | String |
count | Required | Integer |
Example Request
missedQueryHistogram
startDate and endDate.
from searchunify import *
startDate = "2021-06-01"
endDate = "2021-06-04"
count = 5
searchClientId = "5815771e-69dc-11eb-94cc-0242ac120007"
result = missedQueryHistogram(startDate=startDate, endDate=endDate,count=count, searchClientId=searchClientId)
print("The missedQueryHistogram data ", result)
Return the activity on a case.
Parameters
Parameter | Optional / Required | Type |
startDate | Required | String |
endDate | Required | String |
count | Required | Integer |
caseUID | Required | String |
Example Request
searchSessionByCaseUidAuth
from searchunify import *
startDate = "2021-06-01"
endDate = "2021-06-04"
count = 5
caseUID = "5815771e-69dc-11eb-94cc-0242ac120007"
result = searchSessionByCaseUidAuth(
startDate=startDate, endDate=endDate, count=count, caseUID=caseUID)
print("The searchSessionByCaseUidAuth data ", result)
Prints a list of the count most popular documents. For count=5, you will get 5 results. The data is from between startDate and endDate on a search client whose ID is searchClientID. If the searchClientID is not specified, then the call fetches data from all the search clients.
Parameters
Parameter | Optional / Required | Type |
startDate | Required | String |
endDate | Required | String |
searchClientId | Optional | String |
count | Required | Integer |
Example Request
getAllSearchConversion
from searchunify import *
startDate = "2021-06-01"
endDate = "2021-06-04"
count = 1
searchClientId = "5815771e-69dc-11eb-94cc-0242ac120007"
result = getAllSearchConversion(startDate=startDate, endDate=endDate,count=count, searchClientId=searchClientId)
print("The getAllSearchConversion data ", result)
Prints a list of the count documents that are not on the first page. These documents can be boosted to enhance search experience.. For count=5, you will get 5 results. The data is from between startDate and endDate on a search client whose ID is searchClientID. If the searchClientID is not specified, then the call fetches data from all the search clients.
Parameters
Parameter | Optional / Required | Type |
startDate | Required | String |
endDate | Required | String |
searchClientId | Optional | String |
count | Required | Integer |
Example Request
searchConversionNotOnFirstPage
from searchunify import *
startDate = "2021-06-01"
endDate = "2021-06-04"
count = 5
searchClientId = "5815771e-69dc-11eb-94cc-0242ac120007"
result = searchConversionNotOnFirstPage(startDate=startDate, endDate=endDate,count=count, searchClientId=searchClientId)
print("The searchConversionNotOnFirstPage data ", result)
Prints a chart of the popularity (indexData) of all your content sources (indexName). The data is presented in an alphabetical order and includes: objectName, objectData, filterName, filterData, facetName, and facetName. An objectName is a content type and a filter is a high-level facet. The data is from between startDate and endDate.
Parameters
Parameter | Optional / Required | Type |
startDate | Required | String |
endDate | Required | String |
Example Request
searchConversionWithFilters
from searchunify import *
startDate = "2021-06-01"
endDate = "2021-06-04"
result = searchConversionWithFilters(startDate=startDate, endDate=endDate)
print("The searchConversionWithFilters data ", result)
Prints a list of the count most popular searches in a session. For count=5, you will get 5 results. The data is from between startDate and endDate on a search client whose ID is searchClientID. If the searchClientID is not specified, then the call fetches data from all the search clients.
Parameters
Parameter | Optional / Required | Type |
startDate | Required | String |
endDate | Required | String |
searchClientId | Optional | String |
count | Required | Integer |
sessionId | Required | String |
Example Request
searchConversionBySessionId
from searchunify import *
startDate = "2021-06-01"
endDate = "2021-06-07"
count = 5
searchClientId = "5815771e-69dc-11eb-94cc-0242ac120007"
sessionId = "16227428473203630"
result = searchConversionBySessionId(
startDate=startDate, endDate=endDate, count=count, sessionId=sessionId, searchClientId=searchClientId)
print("The searchConversionBySessionId data ", result)
Prints count discussions that have been accessed the most and can be converted into articles. The data is from between startDate and endDate.
Parameters
Parameter | Optional / Required | Type |
startDate | Required | String |
endDate | Required | String |
count | Required | Integer |
internalUser | Optional | String |
Example Request
discussionsReadyToBecomeArticles
from searchunify import *
startDate = "2021-06-01"
endDate = "2021-06-05"
count = 2
internalUser = "all"
result = discussionsReadyToBecomeArticles(startDate=startDate, endDate=endDate, count=count, internalUser=internalUser)
print("The discussionsReadyToBecomeArticles data ", result)
View the list of articles that were consulted before a user created a case.
Parameters
Parameter | Optional / Required | Type |
startDate | Required | String |
endDate | Required | String |
searchClientId | Required | String |
count | Optional | Integer |
internalUser | Optional | String |
searchType | Required | String |
offset | Optional | Integer |
Example Request
getCaseCreatedArticles
from searchunify import *
startDate = "2021-06-01"
endDate = "2021-06-05"
searchClientId = "5815771e-69dc-11eb-94cc-0242ac120007"
internalUser = "false"
searchType = "global"
offset = 0
count = 10
result = getCaseCreatedArticles(startDate=startDate, endDate=endDate, searchClientId=searchClientId, count=count, internalUser=internalUser, searchType=searchType, offset=offset)
print("The getCaseCreatedArticles data ", result)
Returns the articles that were consulted by users who didn't create a case.
Parameters
Parameter | Optional / Required | Type |
startDate | Required | String |
endDate | Required | String |
searchClientId | Required | String |
count | Optional | Integer |
internalUser | Required | String |
searchType | Required | String |
offset | Optional | Integer |
Example Request
getCaseDeflectedArticles
from searchunify import *
startDate = "2021-06-01"
endDate = "2021-06-05"
searchClientId = "5815771e-69dc-11eb-94cc-0242ac120007"
internalUser = "false"
searchType = "global"
offset = 0
count = 10
result = getCaseDeflectedArticles(startDate=startDate, endDate=endDate, searchClientId=searchClientId, count=count, internalUser=internalUser, searchType=searchType, offset=offset)
print("The getCaseDeflectedArticles data ", result)
Find out how many articles have been attached to cases.
Parameters
Parameter | Optional / Required | Type |
startDate | Required | String |
endDate | Required | String |
searchClientId | Required | String |
count | Optional | Integer |
internalUser | Required | String |
offset | Optional | Integer |
Example Request
getAttachedArticles
from searchunify import *
startDate = "2021-06-01"
endDate = "2021-06-05"
searchClientId = "5815771e-69dc-11eb-94cc-0242ac120007"
internalUser = "false"
offset = 0
count = 10
result = getAttachedArticles(startDate=startDate, endDate=endDate, searchClientId=searchClientId, count=count, internalUser=internalUser, offset=offset)
print("The getAttachedArticles data ", result)
From the article URL, find out which cases it has been attached to.
Parameters
Parameter | Optional / Required | Type |
startDate | Required | String |
endDate | Required | String |
searchClientId | Required | String |
count | Optional | Integer |
offset | Optional | Integer |
url | Required | String |
Example Request
getAttachedOnCase
from searchunify import *
startDate = "2021-06-01"
endDate = "2021-06-05"
searchClientId = "5815771e-69dc-11eb-94cc-0242ac120007"
url = "https://cases/salesforce/article/qwe/1"
offset = 0
count = 10
result = getAttachedOnCase(startDate=startDate, endDate=endDate, searchClientId=searchClientId, count=count, offset=offset, url=url)
print("The getAttachedOnCase data ", result)
Prints a list of the count search sessions and the searches conducted in each session. For count=5, you will get 5 results. The data is from between startDate and endDate on a search client whose ID is searchClientID. If the searchClientID is not specified, then the call fetches data from all the search clients.
Parameters
Parameter | Optional / Required | Type |
startDate | Required | String |
endDate | Required | String |
searchClientId | Optional | String |
count | Required | Integer |
Example Request
getSearchQueryInSessions
from searchunify import *
startDate = "2021-06-01"
endDate = "2021-06-05"
count = 10
searchClientId = "5815771e-69dc-11eb-94cc-0242ac120007"
result = getSearchQueryInSessions(startDate=startDate, endDate=endDate, count=count, searchClientId=searchClientId)
print("The getSearchQueryInSessions data ", result)
Prints the number of articles generated on your cases between startDate and endDate on a search client whose ID is searchClientID. If the searchClientID is not specified, then the call fetches data from all the search clients.
Parameters
Parameter | Optional / Required | Type |
startDate | Required | String |
endDate | Required | String |
searchClientId | Optional | String |
count | Required | Integer |
Example Request
getKcsSupportSearchQuery
from searchunify import *
startDate = "2021-06-01"
endDate = "2021-06-05"
searchClientId = "5815771e-69dc-11eb-94cc-0242ac120007"
count = 10
result = getKcsSupportSearchQuery(startDate=startDate, endDate=endDate,count=count, searchClientId=searchClientId)
print("The getKcsSupportSearchQuery data ", result)
Provides search, conversion, page views, case deflection, and case creation data for the argument caseUid.
Parameters
Parameter | Optional / Required | Type |
startDate | Required | String |
endDate | Required | String |
caseUID | Required | String |
Example Request
getSearchSessionByCaseUid
from searchunify import *
startDate = "2021-06-01"
endDate = "2021-06-05"
caseUid = "5815771e-69dc-11eb-94cc-0242ac120007"
result = getSearchSessionByCaseUid(startDate=startDate, endDate=endDate, caseUid=caseUid, count=count)
print("The getSearchSessionByCaseUid data ", result)
Prints a list of the count queries in a search session and the documents accessed during that session. For count=5, you will get 5 results. The data is from between startDate and endDate on a search client whose ID is searchClientID. If the searchClientID is not specified, then the call fetches data from all the search clients.
Parameters
Parameter | Optional / Required | Type |
startDate | Required | String |
endDate | Required | String |
searchClientId | Required | String |
count | Required | Integer |
sessionId | Optional | String |
pageNumber | Optional | Integer |
Example Request
getSearchSessionBySearchSessionId
from searchunify import *
startDate = "2021-06-01"
endDate = "2021-06-05"
searchClientId = "5815771e-69dc-11eb-94cc-0242ac120007"
count = 10
sessionId = "16225418602588530"
pageNumber = 1
result = getSearchSessionBySearchSessionId(startDate=startDate, endDate=endDate, searchClientId=searchClientId, count=count, sessionId=sessionId)
print("The getSearchSessionBySearchSessionId data ", result)
Content
This includes the methods for content source APIs. If you want to use content APIs can directly use these functions.
This function returns all the added content sources.
getContentSources
from searchunify import *
result = getContentSources()
print("The content source list: ", result)
Returns the id, label, name, url, and size of a content source, where size is the number of documents stored in the content source.
Parameters
Parameter | Optional / Required | Type |
contentSourceId | Required | String |
Example Request
getContentSourceById
from searchunify import *
contentSourceId = "2"
result = getContentSourceById(contentSourceId=contentSourceId)
print("The content source data: ", result)
Lists all the objects and fields of a content source in an array. Each element in the array is an object. Each object has four properties: id, label, name, and fields.
The fields element is also an object with six properties: id, name, label, type, isFilterable, and isSearchable. The type property can be an int, a boolean, or a string. isFilterable is a boolean object. If it is true, then the field is used as a facet. isSearchable is also a boolean object. If it is true, then the data stored in the field can be found through search.
Parameters
Parameter | Optional / Required | Type |
contentSourceId | Required | String |
Example Request
getObjectAndFields
from searchunify import *
contentSourceId = "2"
result = getObjectAndFields(contentSourceId=contentSourceId)
print("The object and fields: ", result)
Returns all the documents in your content source in an array and the size of the array. Each element in the array is an object.
Parameters
Parameter | Optional / Required | Type |
contentSourceId | Required | String |
objectId | Required | String |
startFrom | Optional | Integer |
size | Optional | Integer |
Example Request
getObjectSpecificData
from searchunify import *
contentSourceId = "2"
objectId = "2"
startFrom = 4
size = 10
Result = getObjectSpecificData(
contentSourceId=contentSourceId, objectId=objectId, startFrom=startFrom, size=size)
print("The object specific data: ", result)
Return data for particular object id.
Parameters
Parameter | Optional / Required | Type |
contentSourceId | Required | String |
objectId | Required | String |
documentId | Required | String |
Example Request
getObjectSpecificDataWithId
from searchunify import *
contentSourceId = "2"
objectId = "2"
documentId = "34717756"
result = getObjectSpecificDataWithId(
contentSourceId=contentSourceId, objectId=objectId, documentId=documentId)
print("The object specific id data: ", result)
Update any content field or document property in your index. The changes are reflected in your index. This call does not alter data on your content source. For instance, you can update a document title in the index without changing it in the content source.
Parameters
Parameter | Optional / Required | Type |
contentSourceId | Required | String |
objectId | Required | String |
documentId | Required | String |
data | Required | Dict |
Example Request
updateDoucmentById
from searchunify import *
data = {
"tag":
[
"Search clients",
"Customer Experience"
],
"view_href": "https://vimeo.com/ID_HERE",
"title": "SDK bulk upload"
}
result = updateDoucmentById(
contentSourceId=contentSourceId, objectId="2", documentId="ID_HERE", data=data)
print("The document updated: ", result)
Add one or more documents to your search index. bulkUpload can be used instead of crawling from the Admin Console when:
You have only a few documents to add and you don't want to recrawl a large content source
You want to insert new documents into the search index without first deleting it, which happens when an admin crawls from the Admin Console.
Parameters
Parameter | Optional / Required | Type |
contentSourceId | Required | String |
objectId | Required | String |
data | Required | JSON |
Example Request
bulkUpload
from searchunify import *
data = [
{
"id": "1236",
"content": {
"title": "New Templates for Search Clients - Part 1",
"post_time": 1573197537000,
"view_href": "https://vimeo.com/0123456",
"channel_id": "1234567",
"user_id": "01234567890"
}
},
{
"id": "1237",
"content": {
"title": "New Templates for Search Clients - Part 2",
"post_time": 1573197537010,
"view_href": "https://vimeo.com/0123457",
"channel_id": "1234567",
"user_id": "01234567890"
}
},
{
"id": "1238",
"content": {
"title": "New Templates for Search Clients - Part 3",
"post_time": 1573197537210,
"view_href": "https://vimeo.com/0123458",
"channel_id": "1234567",
"user_id": "01234567890"
}
}
]
result = bulkUpload(contentSourceId=contentSourceId, objectId="2", data=data)
print("The content source bulk upload: ", result)
Search
SDK has a search API to make content searchable. You just need to pass parameters as per requirement.
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
getSearchResults
from searchunify import *
Uid = "5815771e-69dc-11eb-94cc-0242ac120007"
searchString = "help"
result = getSearchResults(
uid=uid, searchString=searchString)
print("The search result: ", result)