Terra Dotta Software API Documentation

Back to Terra Dotta Software API Documentation Return to Public Site

getProgramSearchResults

Returns a list of search form elements to be used to create a custom program search page.

URL
http://{site root}/piapi/index.cfm?callname=getProgramSearchResults&ResponseEncoding=json
The value for {site root} would represent your installation URL. The values returned from this function are in the following table.

Table 1: Input arguments for getProgramSearchResults
Table 2: Return values for getProgramSearchResults
Example 1: Calling getProgramSearchResults with JavaScript
Example 2: Calling getProgramSearchResults with ColdFusion

Top

Table 1: Input arguments for **getProgramSearchResults**
Depending on the program type, some of the input parameters may or may not be available. The following is a representation of all available input parameters for all program types.
Standard Input Parameters (jump to call specific input arguments)
Argument	Type	Required	Meaning
ResponseEncoding	String	Optional	The data format to be returned by the API call. The value for `ResponseEncoding` can be one of the following values: Applicable values: (case insensitive) `XML` - eXtensible Markup Language (default) `JSON` - JavaScript Object Notation `SOAP` - Simple Object Access Protocol
CallBack	Boolean	Optional	Used with JSON only to specify if a callback function will be used or not.
CallBackName	String	Optional	Used with JSON only to specify the callback function to use.
Call-specific Input Parameters (jump to standard input arguments)
Argument	Type	Required	Meaning
ItemSort	String	Optional	Sorts search results based on the value you specify.See the SortOrder field for values for specifying that results are returned in ascending or descending order. Applicable values: (case insensitive) `Program_Name` `Program_City` `Program_Country` `Program_Region` Or, a combination of the above. Default: `Program_Name, Program_City, Program_Country, Program_Region`
SortOrder	String	Optional	Sorts search results in ascending or descending order, in conjunction with the value(s) you specify in ItemSort.The default is ascending order, or "asc". Applicable values: (case insensitive) `asc` `desc` Default: `asc`
City	String	Optional	Filters results based on city name.
Country	String	Optional	Filters results based on country name.
Region	String	Optional	Filters results based on region name.
Term	String	Optional	Filters results based on term name.
Params	String	Optional	A serialized sorting of URL-encoded input program parameters (and their types) for use as a filter for which programs to return. You would use this to filter in or out programs based on selected program parameter criteria for each program. Example: If you wanted to create a page that only returned a listing of programs that required a mimimum GPA of 3.0 with Language of Instruction of English or Spanish, your URL-encoded and serialized string might appear similar like the following: p_10009=English%7F%2CSpanish%7F\|p_10009_t=MULTI\|p_10010=3%2E0%7F\|p_10010_t=SELCT This can be broken down into four pipe-delimited values, each of which is URL-encoded: p_10009=English%7F%2CSpanish%7F p_10009_t=MULTI p_10010=3%2E0%7F p_10010_t=SELCT The first line, `p_10009=English%7F%2CSpanish%7F`, is a comma-delimited list of 2 languages, English and Spanish. The delimiter in this case is %2C (a comma, in URL-encoded format). The %7F is a value terminator, which allows the delimited values to contain commas themselves. The value terminator should be placed after each search term, and before the delimiter (%2C). The values 10009 and 10010 are the parameter IDs, which can be obtained from the `getProgramParameters()` API call. The second line p_10009_t=MULTI contains the parameter type. Possible types include: MULTI (multi-select), SELCT (single-select), YESNO (Yes or No), MINIM (Minimum Value), MAXIM (Maximum Value), DATLK (Data table lookup), and DATAX (Data table lookup with search). So the final serialized string would follow this format: p_ID#1=VALUE 1-1{ENCODED TERMINATOR}{ENCODED COMMA}VALUE 1-n{ENCODED TERMINATOR}{ENCODED COMMA}\|p_ID#1_t=PARAM TYPE 1\| p_ID#2=VALUE 2-1{ENCODED TERMINATOR}{ENCODED COMMA}VALUE 2-n{ENCODED TERMINATOR}{ENCODED COMMA}\|p_ID#2_t=PARAM TYPE 2\| p_ID#n=VALUE n-1{ENCODED TERMINATOR}{ENCODED COMMA}VALUE n-n{ENCODED TERMINATOR}{ENCODED COMMA}\|p_ID#n_t=PARAM TYPE n
ProgramName	String	Optional	Keyword search for the program name. Keywords are separated by a comma (,), a semi-colon (;) or a space ( ). To return an exact phrase, the keywords may be within single or double quotes.
ProgramType	Integer	Optional	A filter for specifying the type(s) of programs to return. The default will return Outgoing with SideTrips and OneStep (`1`). Applicable values: `1` - Outgoing with SideTrips and OneStep `2` - Inbound Exchange `3` - Scholarship `4` - Risk Management `14` - Advising Default: `Outgoing with SideTrips and OneStep`
Sponsored	Integer	Optional	A filter for specifying whether or not the programs are StudioAbroad Directory sponsored. Applicable values: `0` - This will omit any programs that are not sponsored. `1` - This will return only programs that are sponsord.
StartRow	Integer	Optional	Starting row of the program list.
EndRow	Integer	Optional	Ending row of the program list.

Top

Table 2: Return values for **getProgramSearchResults**
Depending on the program type, some of the nodes may or may not be available. The following is a representation of all available nodes for all program types.
Return Value	Type	Meaning
RecordCount	Integer	The number of programs returned matching the search criteria.
RowCount	Integer	The number of program records in the programs object - this does not include the program records in the nested featured object.
SearchVerbiage	String	The verbose output of what was search for.
program_id	Integer	The numeric program identifier.
program_name	String	The name of the program.
program_city	String	The name of the program city.
program_country	String	The name of the program country.
program_region	String	The name of the program region.
program_type_id	String	A single-character value representing the type of program. Possible returned values: `1` - Outgoing with SideTrips and OneStep `2` - Inbound Exchange `3` - Scholarship `4` - Risk Management `14` - Advising
program_latitude	String	The latitudinal value of the program location.
program_longitude	String	The longitudinal value of the program location.
bexchangeavailable	Boolean	Indicates whether or not an exchange option is available for this program. 1 = Yes, 0 = No.
benableprogramsave	Boolean	Indicates whether or not a program can be saved to an applicant profile. 1 = Yes, 0 = No.
partners	Object	An object containing partner institutions for the program. This return value is only available when ProgramType has this option enabled. The complex object will resemble the following: <partners> <partner> <program_partner>Partner Institution 1</program_partner> </partner> <partner> <program_partner>Partner Institution 2</program_partner> </partner> </partners>
program_featured	Boolean	Indicates whether or not the program is a featured program. 1 = Yes, 0 = No. If yes, the program will also appear in the featured object (see next).
featured	Object	An object containing featured programs matching the search criteria. This object will return all previous values (above) with the addition of terms and program_description (see next).
FeaturedRecordCount	Integer	The number of featured programs returned matching the search criteria.
terms	Object	An object containing term information for the featured program. This return value is only available when featured programs match the search criteria. The complex object will resemble the following: <terms> <term> <program_term>Fall</program_term> </term> <term> <program_term>Spring</program_term> </term> </terms>
program_desciption	String	This returns the first 250 characters of the program brochure, after HTML has been stripped. A bracketed ellipsis will appear if the content is determined to be longer than 250 characters, appearing as [...].

Using our original call:

http://{site root}/piapi/index.cfm?callName=getProgramSearchResults

We would receive a packet of data in XML format (the default), that might resemble the following:
(the following XML packet is formatted for readability)

<programs>
    <recordcount>2</recordcount>
    <program>
        <program_id>10274</program_id>
        <program_name>
            AIFS in Hyderabad, Academic Year and Semester Programs
        </program_name>
        <program_city>Hyderabad</program_city>
        <program_country>India</program_country>
        <program_region>Asia</program_region>
        <program_type_id>1</program_type_id>
        <program_latitude>17.37528</program_latitude>
        <program_longitude>78.47444</program_longitude>
        <program_featured>0</program_featured>
        <bexchangeavailable>0</bexchangeavailable>
        <benableprogramsave/>
    </program>
    <program>
        <program_id>10291</program_id>
        <program_name>Arcadia University India - Study in India</program_name>
        <program_city>Pune</program_city>
        <program_country>India</program_country>
        <program_region>Asia</program_region>
        <program_type_id>1</program_type_id>
        <program_latitude>18.51957</program_latitude>
        <program_longitude>73.85535</program_longitude>
        <program_featured>0</program_featured>
        <bexchangeavailable>1</bexchangeavailable>
        <benableprogramsave>1</benableprogramsave>
    </program>
    <featured>
        <featuredrecordcount>1</featuredrecordcount>
        <program>
            <program_id>10326</program_id>
            <program_name>Semester at Sea</program_name>
            <program_city>Chennai</program_city>
            <program_country>India</program_country>
            <program_region>Asia</program_region>
            <program_type_id>1</program_type_id>
            <program_latitude>13.08784</program_latitude>
            <program_longitude>80.27847</program_longitude>
            <program_featured>1</program_featured>
            <bexchangeavailable>0</bexchangeavailable>
            <benableprogramsave/>
            <program_description>
                Semester at SeaTerm: Fall, Spring, Summer Description: Semester at Sea gives you a taste of the entire globe as you travel more than 24,000 nautical miles to as many as 13 off-the-beaten-path international destinations ... or to a single fascinating
                [...]
            </program_description>
            <terms>
                <term>
                    <program_term>Fall</program_term>
                </term>
                <term>
                    <program_term>Spring</program_term>
                </term>
                <term>
                    <program_term>Summer</program_term>
                </term>
            </terms>
            <partners>
                <partner>
                    <program_partner>University of Paris</program_partner>
                </partner>
            </partners>
        </program>
    </featured>
</programs>

We can modify the call to return the data in SOAP format by specifying ResponseEncoding=SOAP:

http://{site root}/piapi/index.cfm?callName=getProgramSearchResults&ResponseEncoding=SOAP

We would receive a packet of XML wrapped within a SOAP envelope that might resemble the following:
(the following XML packet is formatted for readability)

<soapenv:Envelope
    xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <soapenv:Body>
        <programs>
            <recordcount>2</recordcount>
            <program>
                <program_id>10274</program_id>
                <program_name>
                    AIFS in Hyderabad, Academic Year and Semester Programs
                </program_name>
                <program_city>Hyderabad</program_city>
                <program_country>India</program_country>
                <program_region>Asia</program_region>
                <program_type_id>1</program_type_id>
                <program_latitude>17.37528</program_latitude>
                <program_longitude>78.47444</program_longitude>
                <program_featured>0</program_featured>
                <bexchangeavailable>0</bexchangeavailable>
                <benableprogramsave/>
            </program>
            <program>
                <program_id>10291</program_id>
                <program_name>Arcadia University India - Study in India</program_name>
                <program_city>Pune</program_city>
                <program_country>India</program_country>
                <program_region>Asia</program_region>
                <program_type_id>1</program_type_id>
                <program_latitude>18.51957</program_latitude>
                <program_longitude>73.85535</program_longitude>
                <program_featured>0</program_featured>
                <bexchangeavailable>1</bexchangeavailable>
                <benableprogramsave>1</benableprogramsave>
            </program>
            <featured>
                <featuredrecordcount>1</featuredrecordcount>
                <program>
                    <program_id>10326</program_id>
                    <program_name>Semester at Sea</program_name>
                    <program_city>Chennai</program_city>
                    <program_country>India</program_country>
                    <program_region>Asia</program_region>
                    <program_type_id>1</program_type_id>
                    <program_latitude>13.08784</program_latitude>
                    <program_longitude>80.27847</program_longitude>
                    <program_featured>1</program_featured>
                    <bexchangeavailable>0</bexchangeavailable>
                    <benableprogramsave/>
                    <program_description>
                        Semester at SeaTerm: Fall, Spring, Summer Description: Semester at Sea gives you a taste of the entire globe as you travel more than 24,000 nautical miles to as many as 13 off-the-beaten-path international destinations ... or to a single fascinating
                        [...]
                    </program_description>
                    <terms>
                        <term>
                            <program_term>Fall</program_term>
                        </term>
                        <term>
                            <program_term>Spring</program_term>
                        </term>
                        <term>
                            <program_term>Summer</program_term>
                        </term>
                    </terms>
                    <partners>
                        <partner>
                            <program_partner>University of Paris</program_partner>
                        </partner>
                    </partners>
                </program>
            </featured>
        </programs>
    </soapenv:Body>
</soapenv:Envelope>

We can modify the call to return the data in JSON format by specifying ResponseEncoding=JSON:

http://{site root}/piapi/index.cfm?callName=getProgramSearchResults&ResponseEncoding=JSON

We would receive a JSON-encoded packet:
(the following JSON packet is formatted for readability)

_cb_getProgramSearchResults({
   "PROGRAM":{
      "2":{
         "PROGRAM_LONGITUDE":73.85535,
         "PROGRAM_REGION":"Asia",
         "PROGRAM_LATITUDE":18.51957,
         "PROGRAM_CITY":"Pune",
         "PROGRAM_ID":10291,
         "PROGRAM_COUNTRY":"India",
         "BENABLEPROGRAMSAVE":1,
         "BEXCHANGEAVAILABLE":1,
         "PROGRAM_TYPE_ID":"1",
         "PROGRAM_FEATURED":0,
         "PROGRAM_NAME":"Arcadia University India - Study in India"
      },
      "1":{
         "PROGRAM_LONGITUDE":78.47444,
         "PROGRAM_REGION":"Asia",
         "PROGRAM_LATITUDE":17.37528,
         "PROGRAM_CITY":"Hyderabad",
         "PROGRAM_ID":10274,
         "PROGRAM_COUNTRY":"India",
         "BENABLEPROGRAMSAVE":"",
         "BEXCHANGEAVAILABLE":0,
         "PROGRAM_TYPE_ID":"1",
         "PROGRAM_FEATURED":0,
         "PROGRAM_NAME":"AIFS in Hyderabad, Academic Year and Semester Programs"
      }
   },
   "RECORDCOUNT":2,
   "FEATURED":{
      "PROGRAM":{
         "PROGRAM_LONGITUDE":80.27847,
         "PROGRAM_CITY":"Chennai",
         "PARTNERS":{
            "PARTNER":{
               "PROGRAM_PARTNER":"University of Paris"
            }
         },
         "PROGRAM_ID":10326,
         "TERMS":{
            "TERM":{
               "3":{
                  "PROGRAM_TERM":"Summer"
               },
               "2":{
                  "PROGRAM_TERM":"Spring"
               },
               "1":{
                  "PROGRAM_TERM":"Fall"
               }
            }
         },
         "PROGRAM_DESCRIPTION":"Semester at SeaTerm: Fall, Spring, Summer Description: Semester at Sea gives you a taste of the entire globe as you travel more than 24,000 nautical miles to as many as 13 off-the-beaten-path international destinations ... or to a single fascinating\n\t\t                [...]",
         "BEXCHANGEAVAILABLE":0,
         "PROGRAM_TYPE_ID":"1",
         "PROGRAM_REGION":"Asia",
         "PROGRAM_LATITUDE":13.08784,
         "PROGRAM_COUNTRY":"India",
         "BENABLEPROGRAMSAVE":"",
         "PROGRAM_NAME":"Semester at Sea",
         "PROGRAM_FEATURED":1
      },
      "FEATUREDRECORDCOUNT":1
   }
});

The data returned using JSON encoding is wrapped within the callback function, _cb_getProgramSearchResults&ResponseEncoding(). By default, all JSON calls are returned within a callback wrapper function in form of:

_cb_callName()

Where callName represents the name of the function you originally called. To override this, you can specify the callBackName argument, as in:

http://{site root}/piapi/index.cfm?callName=getProgramSearchResults&ResponseEncoding=JSON&callBackName=MyCallBackFunction

This call would return the JSON packet wrapped within the callback function, MyCallBackFunction, as in:

_cb_MyCallBackFunction(...json-encoded data...)

In your custom pages, you would then create a corresponding function to handle this custom callback function:

If you would like to receive the data without a callback function, you can use the argument callBack to override this. Specifying a value of false for the callBack argument returns the data without the callback function, as in:

http://{site root}/piapi/index.cfm?callName=getProgramSearchResults&ResponseEncoding=JSON&callBack=false

Note: specifying callBack=true is implied and is unnecessary for returning JSON data with a callback function.

Example 1: Following is an example using JSON and client-side JavaScript to render the program names as link and indicating whether or not the programs are incoming:

Run Example 1 Top
(if your installation does not have any data, this example may not return anything)

Example 2: Following is an example of using ColdFusion to call the API and returning the data in a SOAP envelope:

Run Example 2 Top
(if your installation does not have any data, this example will not return anything)

<cfparam name="responsePacket" default="[ no response ]" />


<cfhttp result="httpCall" method="post" url="#REQUEST.CurrentAccount.AccountURL()#piapi/index.cfm">
    <cfhttpparam name="callName" type="url" value="getProgramSearchResults" />
    <cfhttpparam name="ResponseEncoding" type="url" value="SOAP" />
</cfhttp>


<cfif isXml(httpCall.fileContent)>
    
    <cfset responsePacket = xmlParse(httpCall.fileContent) />
    
    <cfset err = xmlSearch(responsePacket, "//extrainfo") />
    
    <cfif isArray(err) and not arrayIsEmpty(err)>
        
        <cfthrow message="#err[1].xmlText#" />
        <cfabort />
    </cfif>
<cfelse>
    
</cfif>


<h2>Output for 'responsePacket':</h2>
<cfdump VAR="#responsePacket#" />

For additional techniques, be sure to visit the other program calls within these documentation pages.

Back to Terra Dotta Software API Documentation Top