Introduction to the Screen9 XML-RPC API

    Follow

    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.

    Contents

    Prerequisites

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

    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:\n%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:

    <Fault 1: '435: Lookup on media failed with error message: invalid details: invalid mediaid: 123456789 (log ID qyJs8o70Wmvkd7IXQLDC_Q):None'>

     

    Please find a downloadable python example source file with the examples used in this article below.

    Was this article helpful?
    1 out of 1 found this helpful

    Comments