At the 2011 PBS Tech Con in Las Vegas, Edgar Roman gave a presentation on the PBS Interactive APIs.

1. PBS Interactive API Workshop
Edgar Román, Senior Director, Application Development, PBS
April 8, 2011

2. Overview
• TV Schedules API
• COVE API

3. Agenda : TV Schedules API
• Getting Started
• Understanding the models
• Typical usage walkthrough
• What’s next?

4. WPT Example
http://wptschedule.org/schedulenow.php

5. Getting Started: TV Schedules
• How do I get a key?
Fill out this form:
http://open.pbs.org/pbs-api-key-request/
• What kind of data is returned?
– Read-only REST API or XML RPC
– Returns XML or JSON
• How is it protected?
– Simple key based authentication

6. Understanding the models
Provider
(e.g. Cable Vendor)
Head End A Head End B Station
(e.g. Cable Operator) (e.g. KRWG)
Feed 1 Feed 2 Feed 3 Feed 4
(Channel)
Listing X Listing Y Listing W Listing Z

7. Typical usage walkthrough
Start with a Zip code (Optional)
getHeadEndsByZipTagged getStationsByZip
Find a Head End (Cable Operator) Pick a Station
getStationsByHeadend
Select a Feed (Channel)
getFeedsWithMetadata
getAirdatesByFeed
Pull Listings

8. Complete Example
(using unreadable font)
http://tvschedules.pbs.org/tvschedules/api/rest/stationFinder/getHeadendsByZipTagged?
zipcode=20818&apikey=YOUR-API-KEY
http://tvschedules.pbs.org/tvschedules/api/rest/stationFinder/getStationsByHeadend?
headendID=324045&apikey=YOUR-API-KEY
http://tvschedules.pbs.org/tvschedules/api/rest/tvSchedules/getFeedsWithMetadata?
tvDataNames=WETA&headendID=324045&apikey=YOUR-API-KEY
http://tvschedules.pbs.org/tvschedules/api/rest/stationFinder/getStationsByZip?
zipcode=20818&apikey=YOUR-API-KEY
http://tvschedules.pbs.org/tvschedules/api/rest/tvSchedules/getFeedsWithMetadata?
tvDataNames=WETA&apikey=YOUR-API-KEY
http://tvschedules.pbs.org/tvschedules/api/rest/stationFinder/getAirdatesByFeed?
feedID=9854&startTime=2010-09-15T00:00:00&endTime=2010-09-15T02:00:00&apikey=YOUR-API-
KEY

9. getHeadendsByZipTagged?zipcode=20001

10. getStationsByZip?zipcode=20001

11. Agenda : COVE API
• Getting Started
• Understanding the models
• Available Methods
• Typical usage walkthrough
• How to play video
• Authentication
• What’s next?

12. Getting Started: COVE API
• How do I get a key?
– Tell you in a bit
• What kind of data is returned?
– Read-only REST API
– COVE API only returns JSON
• How is it protected?
– Hefty authentication mechanism (So no jQuery
access)
• How can I get video?
– Returns only RTMP links, so roll your own HTML
player

13. Understanding the models
WCFE
Producer A (Mountain
Lake PBS)
Program X Program Y Rustic Living
Video 1 Video 2 Video 3 Camp Little
Pine

14. Methods
• Programs
http://api.pbs.org/cove/v1/programs/
• Videos
http://api.pbs.org/cove/v1/videos/

15. /cove/v1/programs
• Getting all the programs
http://api.pbs.org/cove/v1/programs/
• Getting metadata about one program
http://api.pbs.org/cove/v1/programs/408/

16. /cove/v1/programs/408 - sample

17. /cove/v1/programs - filters
• Getting all national programs
http://api.pbs.org/cove/v1/programs/?filter_producer__name=PBS
• Getting all station programs
http://api.pbs.org/cove/v1/programs/?filter_producer__name=KRMA

18. /cove/v1/videos
• Getting all the videos
http://api.pbs.org/cove/v1/videos/
• Getting metadata about one video
http://api.pbs.org/cove/v1/videos/36032/

20. /cove/v1/videos - filters
• Typical query filters
– Only Available Videos (not expired)
– Of type: Episode, Clip, Segment, Promotion
– That belong to a particular program
– In a compatible encoding format
• Typical output adjustments
– Give me associated images
– Sort by most recent airdate
– Give me 20 at a time

21. /cove/v1/videos – sample query
http://api.pbs.org/cove/v1/videos/
?filter_availability_status=Available
&exclude_type=Chapter
&filter_program=455
&filter_mediafile_set__video_encoding__eeid=
MPEG-4 500kbps
&fields=associated_images
&order_by=-airdate
&limit_start=0&limit_stop=20

23. Typical usage walkthrough
• App starts and pulls a list of all relevant
programs
• Once user selects a program, the app
should query for a short list of relevant
videos
• If a user selects a video, the app
generates the html needed to stream

24. How to play video
• The COVE API doesn’t provide HTML to
play the video (yet)
• Your app has to construct the HTML based
on guidelines at:
http://projects.pbs.org/confluence/display/coveapi/How+to+Render+Videos

25. Sample HTML – Simple link
• From the video JSON, extract:
tp_media_object_id
• Use:
http://video.pbs.org/videos/<tp_media_object_id>
Or
http://video.weta.org/videos/<tp_media_object_id>

26. Sample HTML – Partner Player
• From the video JSON, extract: tp_media_object_id
<iframe id="partnerPlayer" frameborder="0"
marginwidth="0" marginheight="0" scrolling="no"
style="width:512px; height:328px;" src="http://
video.pbs.org/widget/partnerplayer/
<tp_media_object_id>/?player=<player
string>w=512&h=288&chapterbar=true&autoplay=false">
</iframe>

27. Sample HTML – Partner Player
Result

28. Authentication
• Every call to the endpoints must be
authenticated
• Based on OAuth, but is not Oauth
– Two-legged OAuth actually
• Sample implementations provided on the
documentation site
• Front-end a jQuery app using AJAX calls

29. • Active station collaborative efforts to improve existing
products and knowledgebase
– Share ideas
– Compare tricks of the trade
– Solve common problems
– Early product access
• April: COVE API Collaborative Competition
– Participants: KLRU, KPBS, Iowa PTV, TPT, KET,
KCTS, WGBH, Maine PBN, CET, NHPTV
• Coordinated product building activities with openPBS
community
• Visit spiblog.pbs.org to learn more and find out about
future collaborative opportunities

30. How to get COVE API keys
• Fill out this form:
http://open.pbs.org/pbs-api-key-request/
• Will start giving out keys after incubation
lab (early May)
• Check back often in the incubation labs for
new API features and functionality

31. What’s next?
• Easy authentication
– Supporting jQuery
• Provided HTML for video playback
• More exciting queries
– Tell me what you want!

32. Links from this presentation
• This presentation
http://open.pbs.org/post/2011-techcon-slides/
• COVE API Docs
http://projects.pbs.org/confluence/display/coveapi/Welcome
• COVE API url
http://api.pbs.org/cove/v1

33. Questions and Comments
• Edgar Román
emroman@pbs.org