V-Spark Online Help

Using the /search API via GET with Python

The sample code in this section shows an application that uses the /search API's GET method to search the folders associated with a specified company (passed as a parameter) in a V‑Spark installation and saves matching results to a file. Whenever matching items are found, the application calls the API with the output type set to count to identify how many matches were found.

Figure 1. Sample Python Code to search for Audio using GET, Part 1
#!/usr/bin/env python
# Copyright 2017 Voci Technologies  All rights reserved.
# Contains confidential company information.
# Unsupported example code - Not for production use.

import requests
import json
import urllib2

def usage(argv):
    print "Usage:", argv[0], "<sparkhost:port> <root token> <company> <params>"

def main(argv): 1
    if len(argv) != 5: usage(argv) 2
    host, token, company, searchparams = argv[1:]
    tokens = gettokens(host,token)
    folderinfo = getfolderinfo(host,token)
    findfolders(host, folderinfo, tokens, company, searchparams)

def gettokens(host, token): 3
    url = "http://%s/config?token=%s" % (host,token)
    cfg = requests.get(url).json()
    return dict([(comp,d['uuid']) for comp,d in cfg.iteritems()])

def getfolderinfo(host, token): 4
    url = "http://%s/config/folders?token=%s" % (host,token)
    return requests.get(url).json()

def findfolders(host, folder_info, tokens, company, searchparams): 5
    for comp, comp_data in folder_info.iteritems():
        if comp == company:
            print "Searching folders under "+company+" (Token: "+tokens[comp]+")"
            for org, org_data in comp_data.iteritems():
                for folder, folder_data in org_data.iteritems():
                    searchandprintresults(host, tokens[comp], comp, org, folder, \

The major steps shown in Part 1 of this sample Python application are the following:


The main function provides a traditional main routine that shows the order in which functions are called in the application


Check if the right number of command-line arguments have been provided, assign them to appropriate variables if so and identify the expected arguments if not.


Uses the /config API to retrieve the company information from the V‑Spark installation and build a dictionary that only contains the company name and associated token information from the host that was specified on the command line


Uses the /config/folders API to retrieve the folder-level configuration information from the host that was specified on the command line


Initiates the primary loop for the application, which is controlled by the companies that were found in the information that was retrieved from the host specified on the command line. Each company has an associated authorization token (originally stored in the uuid name/value pair), which is the other field for each company entry in the dictionary that was constructed in the gettokens()function. The short name for each company is the data item in the company JSON that provides the linkage between the data from the company and folder sources. This loop then uses this information to search for organization/folder data that is associated with the company whose name was specified on the command line, calling the function that represents the core functionality of this application (searchandprintresults) for each organization and folder.

Figure 2. Sample Python Code to search for Audio using GET, Part 2
def searchandprintresults(host, token, comp, org, folder, searchparams):
    url = "http://%s/search/%s/%s/%s?token=%s%s" % (host, comp, org, folder, token, searchparams) 1
    response = requests.get(url)
    if response.status_code == 200: 2
        print "  URL is "+url
        counturl = url+"&output=count"
        countresponse = requests.get(counturl) 3
        OUTPUT_FILE = comp+"-"+org+"-"+folder+"-search.json"
        print "    Writing Matching JSON for "+countresponse.text+" matches to "+OUTPUT_FILE
        target = open(OUTPUT_FILE, 'w') 4
        data = json.load(urllib2.urlopen(url))
        target.write(json.dumps(data, indent=4, sort_keys=True))

if __name__ == '__main__':
    from sys import argv

The major steps shown in Part 2 of this sample Python application are the following:


Assembles the URL that will be called with the GET method, and then calls that URL.


Tests each folder for audio that matches the search parameters that were specified on the command line, and tests the result of the HTTP call to the REST API to determine if the search was successful.


If the search was successful, the application calls the same URL, appending the output=count parameter in order to retrieve the number of matches found. This number is used in an informative message.


If the search was successful, the application also saves the matching search results to a file whose name is made up of the company, organization, and folder in which matching results were found.

The following is an example of executing this application, assuming that the code shown in Sample Parts 1 and 2 was concatenated and saved to an executable file named search-get-searches.py:

./search-get-searches.py example.company.com 1656744ac845cbe185d1a50a0225d7ac \
    DocTestCo '&client_emotion=positive'

Output from executing this application depends on a V‑Spark installation: the company that you are running it against and the folder data that is associated with that company. That output might look something like the following:

Searching folders under DocTestCo (Token: d457aa9c65a602254e9810c8d08025ad)
  URL is http://example.company.com/search/DocTestCo/DocTestCo-DocTesting/Test01?token=d457aa9c65a602254e9810c8d08025ad&client_emotion=positive
    Writing Matching JSON for 4 matches to DocTestCo-DocTestCo-DocTesting-Test01-log.json