Data API - Documentation | Ustream Developer Network

Data API - Documentation

The Ustream APIs gives you the ability to:

Access content available on the Ustream website.
Search for people, channels and videos.
Pull down useful or interesting systems and operations information such as the most recently started show and total concurrent shows.

Always check out the Ustream API blog for recent updates to APIs, methods, hints and tips, as well as exciting new toys for developers. If you need search capabilities or data on people or content beyond what is discussed here, please contact us at devsupport@ustream.TV.

Limits

We limit the number of API requests to 5,000 per developer key per day so that we can manage demand for the service to deliver the best performance to our users. If you need a higher per day call limit, email us at devsupport@ustream.TV. An application can reduce the number of API requests it needs to make by using a technique we call "parallel request generation". See the section entitled, Request Parallelization.

Definitions & Terms Used in this Documentation

Stream or Show or Broadcast	"Stream" is the technical term for what is colloquially referred to on the Ustream website as a "broadcast" or "show". All Ustream content starts out as a live video stream and can be saved as archived video. Viewers can then play back this saved content. The APIs allow applications to access these archived videos.
User	Users are of three types: individuals who are registered and have broadcasted — we call these users, broadcasters; individuals who are registered but have not broadcasted; and visitors to our site who have not registered. An individual must register to be allowed to broadcast. A person need not be registed to watch streams. Our APIs provide you the ability to call up login information about users but they do not provide personal information about users. The APIs do not provide access to information about users who are not registered with Ustream and are viewing site content. All the content on the Ustream site is generated by users.
Channel	A channel can include multiple live video streams, content such as images, show information (channel URL, show URL, embed code), tags, start time, status (live or offline), viewers for each show on the page, comments, and recorded archives. Every stream is supported by a channel page. The channel page provides a convenient place where users can view the stream because the stream is embedded there by default. Channel content can be shown in many places, namely, Ustream home page, Ustream network pages, or wherever the channel embed is placed. Our APIs allow you to call any or all of a channel's content.
Recorded Video and Recorded Archives	All Ustream content begins as a live stream. While broadcasting, broadcasters can elect to record the live stream as recorded video (also called recorded archives) for later viewing. Archives are saved directly on the Ustream servers and are then made available for viewing under 'Recorded Archives' and in the channel page, broadcaster profile page, or recorded video page.
UID	"UID" as used in the discussion here stands for "Unique IDentifier". The APIs can do general searches and open-ended queries, but they can also take actions against objects. Every object the APIs can reference has a unique identifier of some kind. All have a unique integer ID, and most API calls will return this value. However there are other ways to address objects besides the encoded UID. All the UID methods available, by subject area, are discussed under Fields in a Generalized API Request

Introducing Sample Requests

A Generalized API Request

The following GET is a generalized version of our API format:

GET via URL method:

http://api.ustream.tv/[html|json|xml|php]/[subject]/[subjectUID|scope]/[command]/[otherparams]/?page=[n]&limit=[l]&key=[devkey]

In addition to making API calls via a URL as above, you may also call the API with a normal GET. Here is a generalized GET example via PHP/libCurl, in this example the code returns a serialized PHP object for use in the programmer's code that follows the request:

    <?php
    $request =  'http://api.ustream.tv';
    $format = 'php';   // this can be xml, json, html, or php
    $args .= 'subject=[subject]';
    $args .= '&uid= [ subject UID | scope ]';
    $args .= '&command=[command]';
    $args .= '&params=[other params]';
    $args .= '&page=[n]';
    $args .= '&limit=[l]';
    $args .= '&key=[yourdevkey]';

    // Get and config the curl session object
    $session = curl_init($request.'/'.$format.'?'.$args);
    curl_setopt($session, CURLOPT_HEADER, false);
    curl_setopt($session, CURLOPT_RETURNTRANSFER, true);

    //execute the request and close
    $response = curl_exec($session);
    curl_close($session);

    // this line works because we requested $format='php' and not some other output format
    $resultsArray = unserialize($response);

    // this is your data returned; you could do something more useful here than just echo it
    echo $resultsArray['result'];
    ?>

Table 1: Fields in a Generalized API Request

Fields in a Generalized API Request
API Field	Required Data	Definition
subject	Subject areas: channel \| user \| video \| stream\| system	The area of interest, against which a command will be issued.
uid
	UID for Users: [integerUID \| user login name]	For users, the UID can be either the integer UID or the user name/login that is their public user name used on the Ustream site. Multiple UId and user login can be parallel processed together. See the section on Request Parallelization for details on how to do this.
	UID for Channels: [integer UID \| channelUrl]	For channels, the required UID can be either the integer UID or the web-safe channel title from the channel URL. For example if the channel URL is: `http://ustream.tv/channel/my-first-show` ... then the UID could be in the form of "my-first-show". Multiple channel UIDs of either type (encoded or string) can be parallel processed together. See the section on Request Parallelization for details.
	UID for Videos: [integer UID]	For videos, the required UID is the integer UID. You can extract the UID form the video URL using getVideoId Multiple video UIDs can be parallel processed together. See the section on Request Parallelization for more details.
	for Search: a scope/sort operator	Search scope and sorting is discussed in detail below in the section titled API-based Search Engine. Searches cannot be parallel processed.
command	API verbs and actions	Subject areas share a set of common commands, however some of them have their own unique commands or restrictions. Commands are discussed in detail below, by subject area.
params
	for getValueOf: a property name	The getValueOf command requires you to provide the name of the property that contains the value you seek. Include the property name in the params part of your request.
	for search: search criteria	API-based search requires criteria, meaning a description of what you are trying to find. You include search criteria in the params portion of your request.
key	string	A valid developer key must be submitted with every API call. Submitting an API request without a valid key will return an HTTP "403 Developer Inactive" error.
limit	integer	Maximum records per page (up to 20). The default limit is 20 records.
page	integer	Page of output to return. The default is page=1, and the number of pages available depends on a) how much data there is in the absolute search results and b) how large a page limit you specify.

Request Parallelization

Request Parallelization enables one call to return multiple pieces of information. Instead of making an API request for each piece of data, a parallel request can return multiple pieces of data in one call. A call can request up to ten pieces of information in one parallelized request. However, the information requested must all be for the same subject, such as video or user. The following is an example of a parallelized request:

http://api.ustream.tv/html/channel/chris-pirillo-live;bwanatv;apiuser/getValueOf/status?key=yourDevKey

Notice that the string of unique identifiers separated by semicolons. They are treated exactly like three API requests once the single request hits the parallelized request generator. From this request (example shown above) would issue a single large result object with three Channel objects inside it listed according to the UID submitted, complete with their own set of result fields including any errors each might have generated.

In the Subject area discussions below, a notation of ]|[ designates which commands can be parallel processed.

Data Return

This section describes the data returned for each subject area. It begins with the data structure returned for all subjects and then describes the unique data returned for specific subjects. API calls always return at least these elements:

Table 2: Fields in a Generalized API Response

Fields in a Generalized API Response
API Output Field	Data Types	Definition
results	number \| string \| array \| null	Contains the data requested, or false/null if none found or on failure
msg	string \| null	Contains any debug or feedback information about the processing of the request by Ustream, or null
error	string \| null	Contains any serious error codes, or null
processTime	float	Contains an elapsed time value, in seconds accurate to microseconds.

The "results" element can be complex and returns a single value (a number or string), an array of values in distinct fields, an array of subarrays, or null. Null does not automatically signal an error, but may simply mean that there is no data of the kind you requested. This is especially true of searches if your criteria don't match anything, or when requesting specific values for individual fields when no value is recorded in that field.

The "msg" element can be ignored unless a problem is suspected, in which case it might contain useful feedback. Sometimes "msg" is used to explain how a particular piece of data was calculated or processed. The "error" element may signal a significant failure and should be examined when non-null.

The "processTime" element contains a time value, in seconds accurate to microseconds, that reflects how long it took to process the API call from the time it hit the Ustream API gateway, until the result set was rendered. This time value does not include latency on the Internet.

Requesting Methods and Formats

The API request URL can be written to request XML, JSON (JavaScript Object Notation), PHP, or HTML output.

Table 3: Typical API Request URLs

Typical API Request URLs
API URL Form	Description
`http://api.ustream.tv/xml/`	API output will be as XML.
`http://api.ustream.tv/json/`	API output will be as JSON, a serialized form of Javascript object.
`http://api.ustream.tv/php/`	API output will be a serialized PHP results array, suitable for unserializing and reuse in PHP should you be making your API request in PHP.
`http://api.ustream.tv/html/`	Output will be as raw HTML in the form of a formatted table. This output format is most useful for testing and debugging API requests, and to provide an easy way to see what properties and values are available within a subject area. The table layout makes it easy to understand how arrays are nested, what properties are returned, and what are their data types.

A useful strategy to help you quickly develop your API request is to fashion your exploratory requests as human-readable HTML output and then take the same request and resubmit it as another format (for example, XML or JSON) for actual use in your application. For this reason our examples are in the "URL GET method" format suitable for use in a web browser, and they will return HTML output that is easily readable.

Submitting an API request without a valid key will return an HTTP "403 Developer Inactive" error from the server. This is working as designed, and means you have not used a valid developer account key.

Web work is constantly changing. If you can think of an output format not in the above list that you think would have broad appeal email us at devsupport@ustream.tv.

Description of Subject Areas and Associated Commands

The following section describes all the available commands for each subject — User, Channel, Video, Stream and System.

A URL example is provided for each command and these are useful in learning how to use these commands. All the examples are working code but you will need a valid developer key.

User Subject

The User subject can be addressed using a user integer UID or a user login name.

When using a user login name to establish the request you need to use the exact user name. If you supply a user name that doesn't exist then you will get a "msg" that there was no such user, and empty "results".

Table 4: User Commands

User Commands
Command	Required Input	Description
getInfo	UID ]\|[	The properties that return from the getInfo command represent all that can be known about the user defined by the UID. Note, to protect user privacy, a call will not return personally identifying data such as full name, e-mail address, home town, and the like. Once you run a getInfo, you will have a listing of the values for that UID. getInfo will return all properties whether or not the property has a value. It's a quick way to see the available properties for the "user" subject area. For a detailed discussion of how the user UID is defined please refer to the table Fields in a Generalized API Request earlier in the documentation. URL GET method example: `http://api.ustream.tv/html/user/apiuser/getInfo?key=yourDevKey`
getValueOf	UID , and a property to read (id) ]\|[	This command returns a specific property value for the user. getValueOf can retrieve any of the properties that getInfo provides. For example, getValueOf can return their login name, number of comments, their website of record, or their user rating by other users. URL GET method example: `http://api.ustream.tv/html/user/apiuser/getValueOf/id?key=yourDevKey`
getId	user name OR profile URL ]\|[	This command returns just the integer UID for the user. This is a shortcut method to getValueOf for "uid". The input paramater is a text string containing the username, or else a fully qualified pathname to the profile of the user (http://www.ustream.tv/apiuser ) URL GET method example: `http://api.ustream.tv/html/user/apiuser/getId?key=yourDevKey`
listAllChannels	UID ]\|[	This command returns all the channels belonging to a user. You could get the very same information by performing a search under the "channel" subject area for channels with that associated user ID. URL GET method example: `http://api.ustream.tv/html/user/apiuser/listAllChannels?key=yourDevKey`
listAllVideos	UID ]\|[	This command returns all the videos belonging to the user specified in the UID provided. URL GET method example: `http://api.ustream.tv/html/user/aVgSbbr2IPPMxZlUGKWp2g/listAllVideos?key=yourDevKey`
getComments	UID ]\|[	This command returns any comments for the user profile specified by the UID. They will be returned as an array of comment arrays. Output is truncated to the ten most recent comments. URL GET method example: `http://api.ustream.tv/html/user/apiuser/getComments?key=yourDevKey`
search	scope and criteria	This command is used to search for a user or group of users. In place of the UID, you should use a scope operator (any of all, recent, newest, popular, or live) to specify scope and sorting, and your criteria are passed in the params position of the API request. Search is discussed in greater detail in the section entitled, API-based Search Engine. URL GET method example: `http://api.ustream.tv/html/user/recent/search/username:like:bob?key=yourDevKey`

Channel Subject

Using Channel commands you can request the channel ID, channel owner, tags, embed tag, and comments and much more. The Channel subject can be addressed using either a channel ID or channel URL. Channel UID options are discussed in the table titled Fields in a Generalized API Request. If the channel URL you request does not exist then you will get a "msg" that there was no such channel, and empty "results".

Table 5: Channel Commands

Channel Commands
Command	Required Input	Description
getInfo	UID ]\|[	The properties that return from the getInfo command represent all that can be known about the channel subject. Note, getInfo will return all properties whether or not the property has a value. It's a quick way to see the properties for the "channel" subject area. For a detailed discussion of how the channel UID is defined please refer to the table Fields in a Generalized API Request earlier in the documentation. URL GET method example: `http://api.ustream.tv/html/channel/api-test-show/getInfo?key=yourDevKey`
getValueOf	UID , and an property to read ]\|[	This command returns a specific property's value for that channel. getValueOf can retrieve any of the properties that getInfo provides. This command is used best where you want a specific value about a channel and do not want to process other information about that channel. URL GET method example: `http://api.ustream.tv/html/channel/api-test-show/getValueOf/description?key=yourDevKey`
getId	channel title OR channel URL ]\|[	This command returns just the integer UID for the channel. This is a shortcut method to getValueOf for "uid". The input paramater is a text string containing the channel title as represented in the channel URL, or else a fully qualified pathname to the channel page (http://www.ustream.tv/channel/api-test-show ) For a detailed discussion of how the channel title is extracted from the URL please refer to the table Fields in a Generalized API Request earlier in the documentation. URL GET method example: `http://api.ustream.tv/html/channel/api-test-show/getId?key=yourDevKey`
getEmbedTag	UID ]\|[	This command returns just the embed tag for the show, useful if you want to embed the show in a page. The embed tag is also returned via getInfo. This call is a shortcut. URL GET method example: `http://api.ustream.tv/html/channel/api-test-show/getEmbedTag?key=yourDevKey`
getCusomEmbedTag	UID ]\|[	This command returns just the embed tag for the show, but with sizing and other customization options. URL GET method example: `http://api.ustream.tv/html/channel/api-test-show/getCustomEmbedTag?key=yourDevKey&params=autoplay:false;mute:false;height:100;width:100`	Params: autoplay:false; mute:false; height:100; width:100
listAllChannels	UID ]\|[	This command is similar to the same call in the User subject area, and returns all the channels that belong to the user who is owner of the channel UID provided. Meaning that if you have a UID for a channel you can call this command and get the list of all the other channels (if there are any more) owned by the same user. It may consist of just the same channel listed again because most users have only a single show. But if not, then all channels will be listed in the results. URL GET method example: `http://api.ustream.tv/html/channel/api-test-show/listAllChannels?key=yourDevKey`
getComments	UID ]\|[	This command returns any comments for the channel specified by the UID. They will be returned as an array of comment arrays. Output is truncated to the ten most recent comments. URL GET method example: `http://api.ustream.tv/html/channel/api-test-show/getComments?key=yourDevKey`
getTags	UID ]\|[	getTags is a handy shortcut that returns only user-generated channel tags. If there are tags, they will be returned as an array of tag arrays. Note, today only Ustream.TV users can generate tags for their own channel. URL GET method example: `http://api.ustream.tv/html/channel/api-test-show/getTags?key=yourDevKey`
search	scope and criteria	In place of the unique identifier, you should use a scope operator (any of recent, newest, popular, or live) to specify scope and sorting, and your criteria are passed in the params position of the API request. Search is discussed in greater detail in the section entitled, API-based Search Engine. URL GET method example: `http://api.ustream.tv/html/channel/recent/search/title:like:bob?key=yourDevKey`

Video Subject

You can use the Video subject and video commands to request information about recorded videos, for example how many times a video has been viewed, how viewers have rated it, and any comments about the video they might have left. You can also get the video player URL and complete embed HTML suitable for use on web pages.

Table 6: Video Commands

Video Commands
Command	Required Input	Description
getInfo	UID	The unique identifier for a video can be provided in the API call and will be used to initialize the subject to that video, and return all publicly available information. The properties that return from the getInfo command represent all that can be known about this subject. Note, getInfo will return all properties whether or not the proerty has a value. Note that it's a quick way to see the available properties for the "video" subject area. For a detailed discussion of how the video UID is defined please refer to the table Fields in a Generalized API Request earlier in the documentation. URL GET method example: `http://api.ustream.tv/html/video/38492/getInfo?key=yourDevKey`
getValueOf	UID and an attribute to read	This command returns a specific property value for the video. URL GET method example: `http://api.ustream.tv/html/video/38492/getValueOf/title?key=yourDevKey`
getId	video URL	This command returns just the video UID from the video URL. This is a shortcut method to getValueOf for "uid" URL GET method example: `http://api.ustream.tv/html/video/38492/getId?key=yourDevKey`
getEmbedTag	UID	This command returns just the embed tag for the video. You can use this command if you want to embed the video player in a page. The embed tag is also returned via getInfo. This call is a shortcut. URL GET method example: `http://api.ustream.tv/html/video/38492/getEmbedTag?key=yourDevKey`
listAllVideos	UID	This command is similar to the same call in the User subject area and returns all the other videos belonging to the user who owns the video specified in the UID provided. The benefit of this command is that you can return all the videos for that user once you have identified one video belonging to that user. Videos that are set to "private" by the owner will not be returned. URL GET method example: `http://api.ustream.tv/html/video/38492/listAllVideos?key=yourDevKey`
getComments	UID	This call returns any comments for this video as an array of comment arrays. Only the ten most recent comments will be returned. This API call is a handy shortcut, and returns only the comments. You also get comments via getInfo. URL GET method example: `http://api.ustream.tv/html/video/38492/getComments?key=yourDevKey`
getTags	UID	If there are tags, they will be returned as an array of tag arrays. This API call is a handy shortcut, and returns only the tags. You also get tags via getInfo. URL GET method example: `http://api.ustream.tv/html/video/38492/getTags?key=yourDevKey`
search	scope and criteria	In place of the UID, you should use a scope operator (any of recent, newest, popular, or live) to specify scope and sorting, and your criteria are passed in the params position of the API request. Search is discussed in greater detail in the section entitled, API-based Search Engine. URL GET method example: `http://api.ustream.tv/html/video/recent/search/title:like:bob?key=yourDevKey`

Stream Subject

You can use the Stream Subject to get information about live shows — the newest, most recently started, and the show with the most viewers. You can also return shows randomly, useful if you want to present a constantly changing sample of live broadcasts.

Stream, as the name implies, looks into the Ustream.TV live shows system queue where Ustream keeps records on which streams are currently on the air. This is actually a unique information space apart from Channels or Users and as such contains fields and data available to no other subject. But since there are no permanent objects under this subject most of the commands previously discussed do not entirely apply. Those actons that do are shown in the table entitled Stream Commands, shown below. The Stream subject area is well suited to searching Ustream.TV live content which is constantly changing. For example, Stream can be used to determine what shows have most recently gone on the air, and to see which broadcasters and which of their shows are live.

Table 7: Stream Commands

Stream Commands
Command	Required Input	Description
getRecent	No UID applies, use "all" instead	Fetches one item. Returns information about the most recent show that started broadcasting. URL GET method example: `http://api.ustream.tv/html/stream/all/getRecent?key=yourDevKey`
getMostViewers	No UID applies, use "all" instead	Fetches one item. Returns information about the currently running show having the most viewers. URL GET method example: `http://api.ustream.tv/html/stream/all/getMostViewers?key=yourDevKey`
getRandom	No UID applies, use "all" instead	Fetches one item. Returns information about a currently on-air show pulled entirely at random from the pool of all on-air broadcasts. URL GET method example: `http://api.ustream.tv/html/stream/all/getRandom?key=yourDevKey`
getAllNew	No UID applies, use "all" instead	This command returns all the current live shows that are new where new is defined as newly created by their owners. The current default value for new is any show less than 1 hour old. This default value may be changed by Ustream.TV at any time. The actual rule used to determine newness will be returned in the 'msg' portion of the results set when you use this command. Note, the user account may or may not be new. URL GET method example: `http://api.ustream.tv/html/stream/all/getAllNew?key=yourDevKey`
search	scope and criteria	Instead of the use of "any" in the UID field you can use a scope operator (any of recent, newest, popular, or live) to specify scope and sorting, and your search criteria are passed in the params position of the API request. Search is discussed in greater detail in the section entitled, API-based Search Engine. URL GET method example: `http://ustream.tv/ust_api/stream/recent/search/title:like:bob?key=yourDevKey`

System Subject

The System subject provides information about the status of the Ustream.TV system and APIs. It also serves as a tool for end-to-end testing.

Developers who are just starting out creating applications will find the System subject a useful tool. It is an easy way to see if their application is calling the APIs properly.

Table 8: System Commands

System Commands
Command	Required Input	Description
heartBeat	No UID applies, use "status" instead	Returns an indication of the Ustream.TV service total system health, and provides an end-to-end test of developer key checks, elements of the infrastructure, API dispatching, database access, and output processing. Several values are returned; the current total number of live shows, how many have gone live recently, the title of the show most recently live, and the title of the show (if any) being actively promoted on the Ustream.TV home page. These values change almost constantly under normal conditions. URL GET method example: `http://api.ustream.tv/html/system/status/heartBeat?key=yourDevKey`
ping	No UID applies, use "status" instead	Ping returns a single static string, "pong", as data. It is a very fast, isolated, lightweight test of whether the API request is handled properly. Ping is the fastest request that the API system can handle and is a good test of minimum round-trip latency. As with all API requests the ping result set contains a "processTime" field which is the processing time required in seconds, accurate to microseconds, that it takes to handle API requests. URL GET method example: `http://api.ustream.tv/html/system/status/ping?key=yourDevKey`

API-based Search Engine

Ustream.TV built a powerful, new search engine for developers to use in exploring and accessing Ustream.TV content. It gives them far more visibility into our content than they might expect from the typical content site. Specifically, the API-based search engine gives developers broad and deep visibility into Channel, User and Video records. The API-based search engine issues direct database queries, and our criteria model makes it easy to build simple but powerful requests without any detailed knowledge of the database schema or even the SQL language. The search engine was written to be fast and is completely independent of the Ustream.TV web search engine so it is not burdened by Ustream.TV user searches.

In contrast to the Subject-area commands, the API-based Search Engine is the most general way to pull information about objects known to the APIs. The search command returns one or more objects, their properties depending on the subject area it is run under, or null if nothing was found. When specifying the subject area for the search you do not need to specify a UID for the subject. Instead you define a "scope". All subjects minimally support the same set of scope specifiers. The available scopes are:

Table 9: Search Scope and Sorting Options

Search Scope and Sorting Options
Name	Provides	Description
newest	sorting	Returns items sorted by date created, and applies to all subject areas. When using "newest", the results are returned with the newest first. URL GET method example: `http://api.ustream.tv/html/user/newest/search/username:like:bob?key=yourDevKey`
recent	sorting	Applies only to the Channel and Stream subjects, and regards show streaming dates. Returns shows sorted by date last (or currently if live) launched with the most recent first. "Newest" refers to the show creation date, regardless of whether or not it has ever broadcast. "Recent", in contrast, refers to the date shows have gone live. Note, in the User and Video subject areas "recent" and "newest" can be used interchangeably. In that case the "recent" and "newest" scope are both available to the developer to avoid generating errors, but the output for either will be the same. URL GET method example: `http://api.ustream.tv/html/channel/recent/search/title:like:party?key=yourDevKey`
!newest	sorting	Returns items beginning with oldest first. URL GET method example: `http://api.ustream.tv/html/user/!newest/search/username:like:bob?key=yourDevKey`
!recent	sorting	Returns shows sorted by date last (or currently if live) launched with the oldest first. URL GET method example: `http://api.ustream.tv/html/channel/!recent/search/all?key=yourDevKey`
popular	sorting	Returns items ranked by some measure of popularity, usually the ratings system. When used in the Stream subject area it is always the viewer count. URL GET method example: `http://api.ustream.tv/html/video/popular/search/created::today?key=yourDevKey`
all	scope and sorting	Returns items sorted using the default for that Subject, alphabetically or by unique ID or some other means (see below Properties Available for Search for default sort criteria). Use "any" or "all" to improve the readability of your API requests. URL GET method example: `http://api.ustream.tv/html/channel/all/search/title:like:party?key=yourDevKey`
live	scope and sorting	Live provides the same scope and sorting as recent with the additional functionality of selecting shows that are live. Live returns the shows that are live sorted by most recently launched. The URL GET method for live is: `http://api.ustream.tv/html/channel/live/search/created::now-120?key=yourDevKey` *"Stream" subject area versus* "live" scope: Stream provides a list of live shows (showID and tltle) and the users (userID and login name), who own those shows, that are live at a particular moment. Live scope allows you conduct a keyword search by user or channel to determine if a given user or channel is live at that moment. For example, a live search in the channel subject area for titles like "party" will return all live shows which have "party" in the title. In general if you are conducting searches for streaming shows and users and you are very interested in using all the scope and sort criteria, you will need to search against the Stream subject area. If you are just looking for a particular show currently streaming (for example, checking to see if it is live at all) or a particular user, and you want all the information available on those items when they are found live, then you can work in the specific Channel or User subject area and ask for the live** context. You will get far more information if you do.

Though it can be used in any subject area without generating an error, the recent scope really only applies to shows. Shows have both a date when they were created, a value that never changes, and a date when they were last live on the air, a value that changes every time the show goes live. The following table illustrates how using the newest and recent scopes will result in different output order when performing searches in the Channel subject area. In large data sets the different sort orders could result in entirely different items being returned in the first page of output.

Table 10: How "Newest" and "Recent" Work With Shows

How "Newest" and "Recent" Work With Shows
Show Title	Date Created	Date Last Live
Bob's Stream	Jan 15	Mar 10
Jane's Show	Feb 2	Feb 5
Too Many Cats	Feb 15	Feb 20

Search output when scoped as "newest":
Too Many Cats	Feb 15	Feb 20
Jane's Show	Feb 2	Feb 5
Bob's Stream	Jan 15	Mar 10

Search output when scoped as "recent":
Bob's Stream	Jan 15	Mar 10
Too Many Cats	Feb 15	Feb 20
Jane's Show	Feb 2	Feb 5

In a our generalized API request:

http://api.ustream.tv/html/[subject]/[ subject UID | scope ]/[command]/[other params]?key=[devkey]

... your search criteria are supplied in the last field, named "other params" in the generalized example, and they take the form:

targetProperty:comparison:targetValue

For Ustream.TV APIs, The criteria delimiter is a colon (:). On the back-end these criteria are translated into SQL code. While you do not need a vast knowledge of SQL to use the API query syntax, understanding how SQL makes comparisons may help you understand why you are getting the results you are. The "comparison" term in the example critieria above can be any of:

like: A SQL "LIKE" term that will terminate any targetValue in quotes and add a wildcard "%" at the end, as targetProperty LIKE 'targetValue%'. If you do not want the wildcard, then do not use like, instead use eq .
eq: Compares the targetProperty for absolute equality against the targetValue, and in SQL provides a targetProperty = 'targetValue' term, including quotes.
lt: Compares the targetProperty for numeric or date "less-than", and in SQL provides a targetProperty < 'targetValue' term, including quotes.
gt: Compares the targetProperty for numeric or date "greater-than", and in SQL provides a targetProperty > 'targetValue' term, including quotes.

As a shortcut, if you don't have any criteria and you just want everything then your entire criteria string could consist of just the word "all". Output will be limited to the default number of objects (or else maximum, which ever applies) that the APIs will return. At this time the default number of objects returned per API call is 20, and the maximum is 100.

In addition to the standard comparison values, the Ustream.TV APIs offer a few predefined targetValue that you may find useful. These are mostly concerned with relative dates and times. For example, if you want to return shows that were created in the last 5 minutes, or yesterday, or right now, or on your birthday. The special terms and treatments are detailed in the table below, Special Search TargetValues: Relative Time & Absolute Dates. All these special targetValues are interpreted internally by the search engine to create date and time ranges that will make valid queries against the property you select.

Table 11: Special Search TargetValues: Relative Time & Absolute Dates

Special Search TargetValues: Relative Time & Absolute Dates
targetValue	Description
now	now is interpreted to mean the moment the API gateway received your request. In reality it looks back five seconds from the instantaneous time so as to be somewhat inclusive. Because now is meant to be instantaneous you can specify your comparison using eq for clarity, but it will still be handled as a block of time 5 seconds long no matter what you specify. Example, return all shows that are live now: `lastOnAir:eq:now`
now-N	Where N is an integer greater than zero, representing minutes before now. The API gateway will take now and subtract N minutes and use that new timestamp to define a block of time from that point in the past to now. In this way you can request relative and arbitrary blocks of time N minutes before and leading up to now. You can only look back up to a maximum 10 days before now (being 14,400 minutes, written as now-14400). Values for N greater than the limit are set to the limit. Because now-N is inclusive of a block of time it is always handled as a range of timestamps no matter how you specify your criteria comparison. Example, return all shows that are or were on the air in the last hour: `lastOnAir:gt:now-60`
today	today will be interpreted to mean a block of time starting at midnight according to the server's timezone and ending now. While today is really a block of time and will be queried as such, it is useful to think of it as a point in time as in the example. Example, return all shows that were live today: `lastOnAir:eq:today`
a formatted date	Dates are specified in the form YYYY-MM-DD where YYYY is the 4-digit year (2008), MM is the 2-digit month (01-12) and DD is the 2-digit day (01-31). Note, dates used in this manner will always be handled as eq, regardless of how you build your criteria string. If you want a date range instead of an exact date then use the now-N method discussed above. Unlike now-N, you can specify a date as any arbitrary date in the past. A date targetValue is really a range of time encompassing that entire 24 hour day, and will include all timestamps within the 24 hour period you ask for. Example, return all shows that were created on January 15, 2008: `created:eq:2008-01-15`

If an invalid criteria comparison is specified then the SQL will default to "LIKE" including quotes and wildcard. Whatever criteria were ultimately used are reported back to the calling application in the "msg" element of the results, plus some feedback on how the criteria were processed.

The property name to be compared against is specific to the subject. Not all properties in a subject area can be searched. However, all properties that can be returned by that subject will be returned. The exception to this rule is the Stream subject; all the properties returned in that subject can also be searched. The current list of available search properties (and the data types contained) by class, are:

Table 12: Fields Available for Search Organized by Subject

Properties Available for Search Organized by Subject
Porperty Name	Data Type	Stream	User	Channel	Video
userName	string	yes	yes	yes
title	string	yes		yes	yes
description	string	yes
startTime	timestamp	yes
rating	float	yes		yes
views	integer			yes
created	date			yes	yes
registerdate	date		yes
length	integer				yes
default sort by property:		channelId	userId	channelId	videoId

Here are some hints about search methods and legal values:

Rating is a float usually between 0 to 5.
Views are an integer count starting from zero.
Length (of videos) is in seconds.
UserID and userName only returns users who are registered with Ustream.TV.
All dates supplied in a criteria should follow the MySQL date format for best results (yyyy-mm-dd). The default time is midnight. Currently, criteria with date ranges is not supported. If a search criteria is defined as being equal (eq or =) to a single date then the search engine will define for you a date range equivalent to that 24 hour day, including all the matching records during that period.

In addition to required scope and criteria, you can optionally specify how many records to return at once in the output, and at what page in the output should start returning records. These modifiers are passed in the following optional fields:

limit: Maximum records per page (up to 100). The default limit is 20 records.
page: Page of output to return. The default is page=1, and the number of pages available depends on a) how much data there is in the absolute search results and b) how big a page you specify.

For example, the following combination for limit and page would return items numbered 6 through 10 of your total search results:

http://api.ustream.tv/html/user/newest/search/all?key=yourDevKey&limit=5&page=2

Commonly Used APIs

This section lists a series of commands that illustrate the use of Ustream.TV APIs to perform common tasks. This list was developed through feedback from developers.

The examples provide ways to find highly rated Ustream.TV registered users, live shows with the most viewers, and users whose name matches a certain string. For example, to get all the shows for "tpsradio":

http://api.ustream.tv/html/channel/all/search/title:eq:tpsradio?key=yourDevKey

The following example shows most highly rated shows for "tpsradio" whether they are currently live or not:

http://api.ustream.tv/html/channel/popular/search/title:eq:tpsradio?key=yourDevKey

The following example will return information about all users who have live shows:

http://api.ustream.tv/html/user/live/search/all?key=yourDevKey

The following calls all the live shows (those currently broadcasting) listed in order of most popular first, by performing a search in the Stream subject area:

http://api.ustream.tv/html/stream/popular/search/all?key=yourDevKey

In this example, all channels whose owner name starts with "bob". Again, when searching on "all" as a scope, the results are returned sorted by the default property for that subject:

http://api.ustream.tv/html/channel/all/search/username:like:bob?key=yourDevKey

Sample API Usage

This call enables you to find a unique user ID for the user with the login name "apiuser", or returns NULL if none found.

http://api.ustream.tv/html/user/apiuser/getUserId?key=yourDevKey

This request enables you to find all live channels (shows) owned by the user 63351 and sort by most recently on the air, or return NULL if the user does not have any shows currently on the air.

http://api.ustream.tv/html/stream/recent/search/userID:eq:63351?key=yourDevKey

This call enables you to find a list of all the shows for user "tpsradio". The shows will include both live shows and recorded shows.

http://api.ustream.tv/html/user/tpsradio/listalluserchannels?key=yourDevKey

This call enables you to find all users whose name starts with the string "dog" and rank them by most recently registered accounts.

http://api.ustream.tv/html/user/recent/search/username:like:dog?key=yourDevKey

This call enables you to find all channels whose rating is greater than 4 and rank them by most recent on-air date. They would not need to be actually live for this request to work.

http://api.ustream.tv/html/channel/recent/search/rating:gt:4?key=yourDevKey