The Truveo XML API is the programmatic interface to the Truveo Video Search Engine. Using this API, developers can access the data contained in the Truveo video search index to build a variety custom applications that feature video search functionality.

The Truveo XML API provides the functionality and defines the specification for submitting REST-style queries against the Truveo video search index and retrieving XML-formatted response messages. This page outlines the procedure for accessing this API as well as the format of the supported request and response messages.

To gain access to the Truveo XML API, you must first set up an API account. To create a new API account or view your existing API account, please consult the My API Account page. When you first create a new API account, you will be assigned a unique key, or Application ID. This Application ID is a string that uniquely identifies your organization's application and authorizes it to access the Truveo video search index.

Once you have received your Application ID, you are ready to access API and begin developing your application. This API provides a REST-style interface for accessing the Truveo video search index. With this approach, queries consist of an URL string with a set of specified parameters. Since the entire query is contained in a simple URL expression, queries can be submitted from the browser address bar, the command line, or inside the code of any custom application that can submit an HTTP GET request to a specified URL.

All request URLs for the Truveo XML API begin with the following API Service URL: As indicated by this URL, the host name for the Truveo video search API is 'xml.truveo.com', and the service name is 'apiv3', which represents version 3.0 of the Truveo XML API.

Next, append this API Service URL with the specific parameters that define your query using standard URL formatting. Specifically, each parameter consists of a name-value pair in the format name=value. If the desired value contains special characters such as spaces, ampersands, or equal signs, it should be URL Encoded, which is a standard procedure for converting these special characters to an acceptable character representation. If you would like to specify multiple parameters, each name-value pair should be separated by an ampersand (&). The base URL should be separated from the parameter list by a question mark (?). For example, to submit a query that assigns the values of '1x1jhj64466mi12ia', 'truveo.videos.getVideos', and 'elvis' to the parameters 'appid', 'method' and 'query', use the following expression: To submit this query or any other REST-style query to the Truveo video search engine, simply paste it into your browser's address bar and hit return. Similarly, this REST-style expression can be submitted using any other approach which issues an HTTP GET request to the Truveo XML API. For example, this can be done from the command line or within the code of a custom application developed in virtually any programming language.

Every valid query to Truveo XML API must include values for two required parameters, 'appid' and 'method'. The appid parameter must include the value of a valid Application ID. The method parameter must include the name of a supported API method. This parameter instructs the API about the functionality you would like to invoke and the results you would like to receive. A complete list of all supported methods can be found in the XML API reference documentation. Depending on the specific API method, additional optional parameters can also be specified in the REST-style query. Please consult the documentation to see the full list and description of the supported parameters for each method.

The Truveo XML API will return an XML-formatted message in response to any valid REST-style query. A typical XML response might include detailed metadata for every video in the Truveo video search index that matches a submitted query. The top level tag for each response message is always the <Response> tag, and the XML response will have the following basic format: As you can see from this sample, the specified character encoding for each response is UTF-8, and the <Response> tag will always contain a child tag called <method>. The <method> tag will always contain the name of the API method that was invoked to produce this XML response message. In addition to the <method> tag, many other fields can also be returned in the XML response. The specific fields returned will vary depending on which API method was invoked. Please consult the XML API reference documentation to see the full list and description of the supported fields that are returned in response to each method.

The Truveo XML API returns error messages in response to invalid or improper API calls. Each error message is delivered as a standard XML response with a single child tag called <Error>. This <Error> tag contains a single attribute, Code, which identifies the numerical code for the error. The payload of the <Error> tag contains a text description of the error. A sample error response is shown below: