sd4j: Java API & grabber for Schedules Direct JSON data feeds

sd4j provides a simple, but robust API and grabber for accessing your Schedules Direct listings data from the new Schedules Direct JSON data feeds.

The JSON data feed is still under development and is currently only available to registered testers and so unless you have a test account with Schedules Direct, this API will currently serve no purpose to you. Visit the Schedules Direct forums for more details on the new data feed service.

For those with access to the test environment, this API and grabber is one alternative for accessing and using the data feed service.

NOTE: Since the data feed is still under development and is still considered to be in alpha testing, this API should be considered to be at the same level. Specifically, this API will change without notice until v1.0 is released. Absolutely no backwards compatibility with earlier releases is guaranteed at any time during the v0.x release cycle. Any new release of this API should be considered likely to break existing code that uses a previous build of this API. A new build won't always be a breaker, but current users of this API should be prepared for it during v0.x and should refrain from complaining when it does happen. :) Current releases of the API should be, at best, considered alpha, but in reality are more of a "preview release". API changes can occur due to changes in the Schedules Direcet service by the Schedules Direct team or refactoring/redesign/etc. of the API by myself. Either or both is very likely to happen in the near future and releases of the API during this time will replace existing releases. If you choose to start writing code against this API, be very aware of this fact. Backwards compatibility will not be considered until a v1.0 release of this API is made.

There are two pieces to this project:

• A raw data grabber: A command line tool capable of downloading your listings data and generating that data in a single zip file. This grabber simply downloads and packages the raw JSON data from the Schedules Direct servers into a zip file for you to use as needed.
• A Java API: A complete Java API is available for accessing your listings data programmatically in your Java code. This API makes accessing and using your listings data in Java programs extremely easy and intuitive.

Using the Grabber

Download the standalone package from the downloads section. This package bundles all of the dependencies of sd4j into the single jar and also makes the jar "executable" via the java command line. With this jar file, execute the following:

java -jar sd4j.jar

This will dump all of the command line options to your screen. In its simpliest form, use this command line:

java -jar sd4j.jar -u johndoe -p mypassword -c list

The above command line will dump all listings headends available to the given user. Be sure to use your valid Schedules Direct id and password. You should get output as such:

Available headends for user 'johndoe'
CA00053      Time Warner Cable Beverly Hills
DISH803      DISH Los Angeles Los Angeles
DITV803      DIRECTV Los Angeles Los Angeles
90210        Antenna Over-the-air

To download your EPG data from the Schedules Direct servers, run the following:

java -jar sd4j.jar -u johndoe -p mypassword -c grab

The above command line will download the listings data into a file called epg.zip. The file name, location, etc. can all be configured with additional command line arguments. You can also save your id and password for future use without having to retype them. All of these options are documented by running the program with no arguments.

NOTE: The grabber requires a lot of memory, especially when downloading larger lineups (like DirecTV, Dish, FIOS, etc.). You will probably need to increase the Java heap by adding -Xmx512m right before the -jar in the command line above. If you still see out of memory errors then increase the 512 to 768 or 1024. 64bit Java users can continue to increase the value as needed, though if you ever have to go above 1024 then I'd like to hear about it (so I can fix it).

You can send tvdb.com seriesid updates back to Schedules Direct:

java -jar sd4j.jar -u johndoe -p mypassword -c update -i EP0123456 -cv 12345 -sv 12300

The above command will update the tvdb series id for the program id EP0123456 from 12345 to 12300. The tvdb seriesid is used to pull metadata for programs, such as season/episode data, etc.

Using the API

Grab the sd4j-api package from the downloads section. This version of the jar does not include any of the required dependencies packaged inside the jar. This is to avoid conflict with applications that may already include versions of the required dependencies. Instead, grab the dependencies and include them in your project's classpath manually. The list of dependencies is documented below.

The complete javadocs for the API is packaged in the sd4j-javadocs zip file in the downloads section.

TODO: A little more description, maybe a quick code example.

Dependencies

• commons-logging v1.1.1+
• commons-io 2.4
• args4j 2.0.21
• log4j 1.2.x (recommended, not required)
• Apache HttpClient 4.2.1+ (specifically, the httpcore, httpclient and fluent-hc jars are needed)
• json.org (download and build the Java JSON parser from https://github.com/douglascrockford/JSON-java)
• commons-compress 1.4.1

Java Version

This project is developed and built using Java SE 1.6, but the builds are targeted for Java SE 1.5. You must run at least Java 1.5 to use this API. Java 1.7 should work, but has not been tested. I wouldn't expect any problems as long as the dependencies above work with Java 1.7.