V-Spark Online Help

Using the /search API via POST with Python

The sample code in this section shows an application with exactly the same functionality as the application shown in Using the /search API via GET with Python, but uses the /search API's POST method rather than the GET method. In this application a JSON file containing the /search parameters is passed as a command-line argument rather than the parameters themselves. As this example shows, reading parameters from a JSON file makes it easy to programmatically modify those parameters if you need to issue the same call in a slightly different fashion.

Figure 1. Sample Python Code to Search for Audio using POST, 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> <JSON-params-file>"

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

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, searchparamfile): 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 identifying 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 POST, Part 2
def searchandprintresults(host, token, comp, org, folder, searchparamfile):
    url = "http://%s/search/%s/%s/%s?token=%s" % (host, comp, org, folder, token)
    with open(searchparamfile) as json_file: 1
        param_data = json.load(json_file)
    header = {'Content-type': 'application/json'}
    response = requests.post(url, data=json.dumps(param_data), headers=header)
    if response.status_code == 200: 2
        print "  URL is "+url
        param_data["output"] = "count".decode('utf-8') 3
        countresponse = requests.post(url, data=json.dumps(param_data), headers=header)
        OUTPUT_FILE = comp+"-"+org+"-"+folder+"-post-search.json"
        print "    Writing Matching JSON for "+countresponse.text+" matches to "+OUTPUT_FILE
        with open(OUTPUT_FILE, mode='wb') as localfile: 4

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 POST method, reads in the JSON file that contains the parameters with which you want to call the API, sets the correct header value that is required to identify the type of data that you are passing to the POST call, 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 modifies the in-memory representation of the JSON file to specify that the next call that uses that data will request the number of matching results rather than the matching data. 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-post-searches.py:

./search-post-searches.py example.company.com 1656744ac845cbe185d1a50a0225d7ac \
    DocTestCo summary-and-client-emotion.json

Output from executing an 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
    Writing Matching JSON for 4 matches to DocTestCo-DocTestCo-DocTesting-Test01-search.json