Skip to content

Terra Dotta Software API Documentation


Back to Terra Dotta Software API Documentation Return to StudioAbroad

getFeaturedPrograms

Returns a list of active featured programs by their associated program type(s).

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


Top
Table 1: Input arguments for getFeaturedPrograms
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)
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
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
Program_Active Integer Optional A filter parameter to check whether the program is active.
    Applicable values:
  • 1 - Return only active programs (default)
  • 0 - Return only inactive programs
  • (blank) - Return both inactive and active programs; as in, &Program_Active= (without a value)


Top
Table 2: Return values for getFeaturedPrograms
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
program_id Integer The numeric program identifier.
program_name String The name of the program.
program_city String The name of the host program city.
program_country String The name of the host program country.
program_region String The geographical region in which the program is hosted.
program_latitude Decimal Latitude coordinate for the the program location.
program_longitude Decimal Longitude coordinate for the the program location.
program_type_id Integer An integer value that represents the type of program it is.
bexchangeavailable Integer Whether or not the exchange option is available for this program.
program_description String The description of the program.
Terms Object Container object for all terms for the program.
Partners Object Container object for all program partners / sponsors.


Using our original call:
http://{site root}/piapi/index.cfm?callName=getFeaturedPrograms
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>10008</program_id>
        <program_name>Paris Semester Abroad</program_name>
        <program_city>Paris</program_city>
        <program_country>France</program_country>
        <program_region>Europe</program_region>
        <program_latitude>48.85341</program_latitude>
        <program_longitude>2.3488</program_longitude>
        <program_type_id>1</program_type_id>
        <bexchangeavailable>1</bexchangeavailable>
        <program_description>
        Paris Exchange ProgramThe Paris Exchange program is partnered with the American University at Paris (AUP) and offers applicants a fall semester or year long term in Paris or America. For American StudentsThe French language component of this program[...]
        </program_description>
        <terms>
            <term>
                <program_term>Academic Year</program_term>
            </term>
            <term>
                <program_term>Fall</program_term>
            </term>
            <term>
                <program_term>Spring</program_term>
            </term>
        </terms>
        <partners>
        <partner>
        <program_partner>University of Paris</program_partner>
        </partner>
        </partners>
    </program>
    <program>
        <program_id>10326</program_id>
        <program_name>Semester at Sea</program_name>
        <program_city>Adelaide</program_city>
        <program_country>Australia</program_country>
        <program_region>Australia/Pacific Islands</program_region>
        <program_latitude>-34.93333</program_latitude>
        <program_longitude>138.6</program_longitude>
        <program_type_id>1</program_type_id>
        <bexchangeavailable/>
        <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>
        </partners>
    </program> 
</programs> 

We can modify the call to return the data in SOAP format by specifying ResponseEncoding=SOAP:
http://{site root}/piapi/index.cfm?callName=getFeaturedPrograms&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>10008</program_id>
        <program_name>Paris Semester Abroad</program_name>
        <program_city>Paris</program_city>
        <program_country>France</program_country>
        <program_region>Europe</program_region>
        <program_latitude>48.85341</program_latitude>
        <program_longitude>2.3488</program_longitude>
        <bexchangeavailable>1</bexchangeavailable>
        <program_description>
        Paris Exchange ProgramThe Paris Exchange program is partnered with the American University at Paris (AUP) and offers applicants a fall semester or year long term in Paris or America. For American StudentsThe French language component of this program[...]
        </program_description>
        <terms>
            <term>
                <program_term>Academic Year</program_term>
            </term>
            <term>
                <program_term>Fall</program_term>
            </term>
            <term>
                <program_term>Spring</program_term>
            </term>
        </terms>
        <partners>
        <partner>
        <program_partner>University of Paris</program_partner>
        </partner>
        </partners>
    </program>
    <program>
        <program_id>10326</program_id>
        <program_name>Semester at Sea</program_name>
        <program_city>Adelaide</program_city>
        <program_country>Australia</program_country>
        <program_region>Australia/Pacific Islands</program_region>
        <program_latitude>-34.93333</program_latitude>
        <program_longitude>138.6</program_longitude>
        <bexchangeavailable/>
        <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>
        </partners>
    </program> 
</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=getFeaturedPrograms&ResponseEncoding=JSON
We would receive a JSON-encoded packet:
(the following JSON packet is formatted for readability) 
_cb_getFeaturedPrograms(
{
	"PROGRAM":
	{
	"19":
		{
		"PROGRAM_CITY":"Paris",
		"PROGRAM_COUNTRY":"France",
		"PROGRAM_REGION":"Europe",
		"PROGRAM_LATITUDE":"48.85341",
		"PROGRAM_LONGITUDE":"2.3488",
		"PARTNERS":"",
		"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\t\t\
				t\t\t[...]",
		"BEXCHANGEAVAILABLE":"",
		"PROGRAM_NAME":"Semester at Sea"
		},
	"35":
		{
		"PROGRAM_CITY":"Adelaide",
		"PROGRAM_COUNTRY":"Australia",
		"PROGRAM_REGION":"Australia/Pacific Islands",
		"PROGRAM_LATITUDE":"48.85341",
		"PROGRAM_LONGITUDE":"2.3488",
		"PARTNERS":"",
		"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\t\t\t\t\t[...]",
		"BEXCHANGEAVAILABLE":"",
		"PROGRAM_NAME":"Semester at Sea"
		},
	"RECORDCOUNT":2
}
);


The data returned using JSON encoding is wrapped within the callback function, _cb_getFeaturedPrograms(). 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=getFeaturedPrograms&Program_ID=10001&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:
<script language="JavaScript" type="text/javascript">
<!--
// <![CDATA[
function _cb_MyCallBackFunction(data)
{
    // put additional routines here
}
// ]]>
//-->
</script>
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=getFeaturedPrograms&ResponseEncoding=JSON&Program_ID=10001&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 of using ColdFusion to call the API and returning the data in a SOAP envelope:
Run Example 1 Top
(if your installation does not have any data, this example will not return anything)

<!---// local variables //--->
<cfparam name="responsePacket" default="[ no response ]" />
<cfparam name="url.program_id" default="10001" />

<!---// connect to the API (GET or POST) //--->
<cfhttp result="httpCall" method="post" url="#REQUEST.CurrentAccount.AccountURL()#piapi/index.cfm">
    <cfhttpparam name="callName" type="url" value="getFeaturedPrograms" />
    <cfhttpparam name="ResponseEncoding" type="url" value="SOAP" />
    <cfhttpparam name="Program_id" type="url" value="#url.program_id#" />
</cfhttp>

<!---// ensure the response is in XML format //--->
<cfif isXml(httpCall.fileContent)>
    <!---// parse response //--->
    <cfset responsePacket = xmlParse(httpCall.fileContent) />
    <!---// check to see if an error was thrown //--->
    <cfset err = xmlSearch(responsePacket, "//extrainfo") />
    <!---// an error was thrown //--->
    <cfif isArray(err) and not arrayIsEmpty(err)>
        <!---// throw error //--->
        <cfthrow message="#err[1].xmlText#" />
        <cfabort />    
    </cfif>
<cfelse>
    <!---// additional error checking //--->
</cfif>

<!---// additional code goes here //--->
<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