Preface

Note

During API-20191022 beta phase, the URL to use is https://w8xmzqba6c.execute-api.us-east-1.amazonaws.com/20191022 Once the API goes to production, the URLs will be live.

Any user with a valid Schedules Direct login may use the API. Developers may send email to grabber@schedulesdirect.org for assistance, but the Developers Corner should be your first stop.

Note

Our contract with our upstream provider limits us to providing data for individual use only and exclusively to Open Source software; using an open source program as "middleware" and then pushing data into a commercial application violates the terms of service. Please see the subscriber agreement if you have questions. If you would like to use the data in a commercial, academic or governmental environment send an email to Kyle Brownell at Gracenote.

This page describes API version 20191022. Last update: 2020-01-22.

The service implements a RESTful interface.

There are multiple tools which can assist if you're implementing a REST client; two good ones are Postman and JSONlint

DateTime responses are in "Z" / UTC time. There are no Daylight Saving Time adjustments made in any DateTime values.

Design goals

From the outset, the design goals of the JSON API was to minimize the amount of data which needed to be sent from the server to the client. Throughout the API you will see that it makes liberal use of "modified" and MD5 hashes to allow a client to determine if it needs to perform an update on any particular piece of information. To reduce server-side processing, Schedules Direct will not maintain a list of channels that you want sent to you; it's up to the client to request what they want when they make the request. (This makes the server architecture almost stateless and allows us to scale easily)

The API architecture allows your client to quickly determine things like:

  • Has the lineup mapping (the list of which content is on which channel) changed? If yes, then the modified date of the lineup will be updated. If your copy has a different modified date, then download the update. (It is still up to your client to determine whether the lineup should be applied automatically, whether you will run a diff of the existing vs. the new)
  • Has the schedule for a stationID changed since the last time you downloaded it? If yes, download a new one. Schedule updates happen multiple times per day, but not all schedules may have an update.
  • Have there been any updates to the programs in the schedule? The schedule for a stationID will tell you the programID that's in a timeslot, and the MD5 hash of the data for that program. But it doesn't automatically include the program data itself - that's a separate API call. Your application could compare the hash in the schedule with the hash of your local copy of the program data. If the MD5 hash in the schedule data is the same as what you already have from a previous download, then there's nothing to do. Or, the same program may be played multiple times in a 2 week period over multiple stationIDs. It will still be the same program, with the same MD5 hash. Your application would only need to download it once as part of a batch request you send to the server for programIDs that you require. If it's different, then there may be new guest stars, or a late-breaking program update has occurred, so your client can include the programID in the batch request of new / updated programIDs.

Tasks your client must perform

A client process flow during initial configuration would be:

  • Using a web browser, configure an account at the Schedules Direct website. Accept the Terms of Service, etc.

Using a grabber client:

  • Set a useragent in the header of your request. The useragent will allow Schedules Direct and the developers to work together if there are bugs; please see http://forums.schedulesdirect.org/viewtopic.php?f=17&t=2597

  • Obtain the token for this session. If the token response indicates that the system is offline, you should disconnect.

  • Obtain the current status.

    • If the system status is "Offline" then disconnect; all further processing will be rejected at the server. A client should not attempt to reconnect for 1 hour.
  • Obtain the list of lineups in the postal code.

  • Allow the user to select which lineup they want data for. Use the PUT function to add that lineup to their account at Schedules Direct. By default, a user may have 4 lineups in their account, but this can be modified by sending a request through the Schedules Direct ticket service or by sending an email to grabber@schedulesdirect.com

  • You may perform 6 "adds" in a 24 hour period. The status response will indicate the number of lineup changes remaining.

  • Download the lineup. This will provide the user the mapping of channels, callsigns and stationIDs.

  • Allow the user to select which stations they wish to receive data for - this is done at the client; the server does not maintain a list of stations for the user, only the lineup name.

  • Send a request for the schedules for those stationID's to the server. You may request the schedule data for all days for the stationID, or a subset. Use the "date" element in the request if you'd like to specify which days to get the schedule for. This can also be used to process data in batches if you have a memory or CPU-limited client.

  • Process the schedules; each stationID will typically contain at least 14 days of data. Some stationID's may have more than 14 days; some which are outside of North America may have as little as 7 days if the broadcaster doesn't provide daily updates to our upstream.

  • Determine which programID's need to be downloaded. During an initial download, the client will have an empty cache of programID's / MD5 hashes, so the client will need to download all relevant programID's.

Note

There is a hard-coded limit on the server; you may only request 5000 programIDs, schedules, or schedule MD5's per request. (But you may issue multiple requests if you need more than 5000 pieces of information from the server.) There is a 10-minute timeout on the server; if the response to your request can not be sent to you within 10 minutes, it will terminate at the 10 minute point. So, do not request 5000 programIDs if you are on a 33.6Kbps dial-up.

Once the client is in a steady state:

  • Obtain the token for this session. If the token response indicates that the system is offline, you should disconnect.
  • Obtain the current status.
  • If the system status is "Offline" then disconnect; all further processing will be rejected at the server. A client should not attempt to reconnect for 1 hour.
  • Check the status object and determine if any lineups on the server have newer "modified" dates than the one that is on the client. If yes, download the updated lineup.
  • If there are no changes to the lineups, send a request to the server for the MD5 hashes of the schedules that you are interested in. If the MD5 hash for the schedule is the same as you have locally cached from your last download, then the schedule on the server hasn't changed and your client should disconnect.
  • If the MD5 hash for the schedule is different, then download the schedules that have different hashes.
  • Parse the schedule, determine if the MD5 of the program for a particular timeslot has changed. If the programID for a timeslot is the same, but the MD5 has changed, this means that some sort of metadata for that program has been updated.
  • Request the "delta" programID's as determined through the MD5 values.

Requesting only stationID's and programID's that the user is interested in will minimize the time and data required in each download. Downloading only schedules and programs that are different than what you have already downloaded will minimize the download time and processing your client must perform.

Data updates occur seven days a week. At a minimum there will be two data refreshes per day. Use of the MD5 for the schedule will allow your client to determine if a particular stationID has an updated schedule. (Not all stationIDs may be refreshed in a particular time block if there are no server-side updates.)