BasicUsage

Introduction

sdjson 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, but access is now available to all registered users of www.schedulesdirect.org who have an active subscription (including an active trial subscription). Visit the Schedules Direct forums for more details on the new data feed service.

NOTE: Since the data feed is still under development, 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.x 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 latest version of the grabber from the files section. This package bundles all of the dependencies of sdjson into the single jar and also makes the jar "executable" via the java command line. With this jar file, execute the following:

java -jar sdjson.jar

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

java -jar sdjson.jar --username johndoe --password mypassword 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 sdjson.jar --username johndoe --password mypassword grab

The above command line will download the listings data into a file called sdjson.epg. 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).

Using the API

Details on using the Java API are available here. That link includes details on required dependencies, etc. The API portion of this project is now exclusively available via the Maven Central Repository, which makes inclusion of the project that much easier for Maven users.