Note that the XML-RPC API is a legacy API and is no longer being developed, we recommend using the REST API instead.

This is the first article in the introduction to the Screen9 XML-RPC API. The articles in this section are intended for developers integrating the Screen9 API in a web service or similar. All code examples in this article series will be given in python. The examples used in this article can be downloaded in Python source code attachment.

Contents

• Prerequisites
• Connecting to the service
• Listing videos
• Displaying a video
• Searching for videos
• Errors 

Prerequisites

Before you get started programming, make sure you have access to the following:

• The complete API documentation
• Customer ID (also called "Custid" and can be found on the API page of Console)
• Your account must be opened to the IP address(es) where you are running your development environment. 
• Your firewalls must be configured to allow traffic from and to xmlrpc.screen9.com.

Connecting to the service

In this example we use python's library xmlrpclib to establish the connection to the service.

URLs for accessing the XML-RPC API are:

• http://xmlrpc.screen9.com (standard HTTP port 80)
• https://xmlrpc.screen9.com (standard HTTPS port 443)

#!/usr/bin/env python

from xmlrpclib import Server

CUSTID = # Customer ID assigned by Screen9
HOSTNAME = 'xmlrpc.screen9.com'
PORT = 80
server = Server('http://%s:%i' % (HOSTNAME, PORT))

Once the server connection is established, we can start sending API requests. All API requests contain a common parameter which has information about the end user's browser and about which API version the request is connecting to.

common = {
 'browser' : 'Browser user-agent',
 'refer' : 'HTTP referer',
 'userip' : '0.0.0.0',
 'custid' : CUSTID,
 'version' : '2.0' }

We're now ready to start accessing data from the API. Below is a simple example that prints the number of videos in the account.

try:
    video_count = server.countMedia(common)
    print "Account contains %d videos" % video_count
except (Exception), e:
    print e

Listing videos

Now that we have a connection to the API we can start working with the video content in the platform. Here's an example of how to list videos which have been successfully transcoded. The example lists the 10 most recently uploaded videos with the following meta data:

• Mediaid - the unique identfier for all objects in the Screen9 OVP
• Title
• Thumbnail

try:
    fields = ['mediaid','title', 'thumbnail']
    filters = {'status' : 'successful', 'mediatype' : 'video' }
    video_list = server.listMedia(common, fields, filters, 'posted', 10, 1)
except (Exception), e:
    print e

The resulting video_list is an array which contains a struct with the requested meta data.

Displaying a video

 We now move forward in our example and want to display the first video from the list of 10 videos that we got from the previous example. We also want to know some more information about that video so we ask for the duration and the number of views for the video. We start by printing the additional information.

video = video_list[0]
additional_fields = ['duration', 'downloads_started']
details = server.getMediaDetails(common, video['mediaid'], additional_fields)
duration = int(details['duration'] / 1000)
print "Latest uploaded video (""%s"") is %d seconds long and has been viewed %d times." % (video['title'], duration, details['downloads_started'])

We now want an embed code to place on the webpage so that visitors can see the video. The requested embed code is of type universal which means that it will automatically work on mobile devices and flash capable devices.

embedcode = server.getPresentation(common, video['mediaid'], 0, {'embedtype' : 'universal'})
print "This is the embedcode for that video:
%s" % (embedcode['universal'])

Searching for videos

 Searching for videos in the platform is similar to the listMedia call with the additional query parameter as well as specifying which fields to search in. In the example, we search the tags, title and description fields.

query = 'test'
search_results = server.search(common, query, ['tags', 'title', 'description'], fields, filters, 'posted', 5, 1)
print "%d results for query ""%s""" % (search_results['count'], query)

Errors

Errors in the communication with the API are handled as exceptions. Here is an example where we deliberately use an invalid mediaid to ask for meta data using the getMediaDetails call.

fakeid = '123456789'
try:
    server.getMediaDetails(common, fakeid, fields)
except (Exception), e:
    print e

This results in the following output:

Python example source file with the examples used in this article is available for download below.