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.

 

Copy

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.

Copy

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

Copy

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

Copy

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

Copy

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

Copy

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

Copy

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

Copy

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

Copy

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

Copy

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

Copy

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

Copy

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

Copy

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

Copy

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

Copy

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

Copy

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

Copy

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

Copy

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

Copy

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

Copy

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

Copy

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

Copy

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

Copy

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

Copy

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.

Copy

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

Copy

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

Copy

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

Copy

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

Copy

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

Copy

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

 

Copy

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

Copy

getSearchResults

from searchunify import *

Uid           =  "5815771e-69dc-11eb-94cc-0242ac120007"
searchString =  "help"
result       = getSearchResults(
   uid=uid, searchString=searchString)
print("The search result: ", result)