Home

Notes

Page originally copied from [Derek Battams' java grabber](http://sdjson.googlecode.com) with his permission.

This page describes API version 20130107.

As of 2012-12-30, the "baseurl" is "https://data2.schedulesdirect.org"

Requests are sent to the "$baseurl/request.php" page as JSON.

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

When a client wishes to obtain data from the server, it should first connect to "$baseurl/request.php" and provide login credentials.

{"request":{"password":"{foorbarbaz}","username":"[email protected]"},"object":"randhash","action":"get","api":20130107}

The server will respond with one of the following:

{"response":"OK","code":200,"randhash":"f43948ea193d3b3bad987d9443da4441"} {"response":"ERROR","code":401,"message":"Invalid login information.","datetime":"2012-12-18T16:39:10Z"} {"response":"ERROR","code":401,"message":"Account expired.","datetime":"2012-12-18T20:57:37Z"}

The "randhash" response must be passed to the server for all requests with one exception: the server can provide a list of headends in a particular zip code or postal code without a randhash. This is functionality exists for the qamscanner program detailed elsewhere on this wiki.

In the following examples, where you see the string "{randhash}", it is the literal randhash from the response, such as "f43948ea193d3b3bad987d9443da4441" from the example above. In a real request, the randhash will be a random value.

The server supports various commands.

A typical request will contain the following fields:

Field Name	Optional	Description	Notes
api	N	The current API version is 20130107 - if not provided, then the server will reject the request.
action	N	"get", "add", "delete", "update"
object	N	Valid "get" objects are: "status", "headends", "lineups", "programs", "schedules". Valid "add" objects are "headends". Valid "delete" objects are "headends". Valid "update" objects are "password" and "metadata"
randhash	Y	randhash obtained after logging in and providing proper credentials. Used to authenticate user requests.	A randhash is valid for 24 hours, unless a new valid randhash is generated.

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:

• Obtain the randhash for this session.
• 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 headends for the postal code.
• Allow the user to select which headends they want data for. Use the "add" function to add that headend to their account at Schedules Direct. A user may have 4 headends in their account. You may perform 6 adds in a 24 hour period.
• Download the lineups for the headends. This will provide the user the mapping of channels, callsigns and station ids.
• Allow the user to select which stations they wish to receive data for.
• Send a request for the schedules for those station id's to the server.
• Process the schedules; each schedule for each station id will contain two weeks of data.
• Determine which program id's need to be downloaded. During an initial download, the client will have an empty cache of program id's / MD5 hashes, so the client will need to download all relevant program id's.

NOTE: the server has been successfully tested with over 30,000 program id requests, but the response may overload the client. You are strongly encouraged to chunk your requests to prevent your client from running out of memory.

Once the client is in a steady state:

• Obtain the randhash for this session.
• 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 headends on the server have newer "modified" dates than the one that is on the client. If yes, download the updated lineup for that headend.
• If there are no changes to the headends, check the last data update in the status object. If the last data update on the server is the same as what the user has saved, then there are no updated schedules, and the client should disconnect.
• If the last update data is newer, then download the schedules for the station id's that the user has selected.
• Parse the schedule, determine if the md5 of the program for a particular timeslot has changed. If the program ID 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" program id's as determined through the md5 values.

Requesting only station id's and program id's that the user is interested in will minimize the time and data required in each download.

Data updates occur six days a week, Monday through Saturday and are usually complete by 10:00 Central Standard Time.

GET

status

Send:

{"randhash":"f43948ea193d3b3bad987d9443da4441","object":"status","action":"get","api":20130107}

The response from the server:

{"account":{"expires":"2013-06-22T05:16:29Z","messages":[],"maxHeadends":9999},"headend":[{"ID":"0005995","modified":"2012-12-28T14:17:10Z"},{"ID":"DISH561","modified":"2012-12-29T16:08:03Z"},{"ID":"DITV561","modified":"2013-01-03T14:41:36Z"},{"ID":"IL57303","modified":"2012-12-11T22:46:03Z"}],"lastDataUpdate":"2013-01-12T14:39:09Z","notifications":["Test message 1.","Test message 2."],"systemStatus":[{"date":"2012-12-17T16:24:47Z","status":"Online","details":"All servers running normally."}],"response":"OK","code":200,"serverID":"AWS-micro.1"}

The status response contains the following information:

• "account" - specific details about the account. "expires" is the "Z" date when the account will expire.
• "messages" will be a string array with any specific messages for this user.
• "maxHeadends" - the maximum number of lineups headends for this user.
• "headend" - information about the headends this user has configured. "ID" is the headend designation. The "modified" field indicates the last update. This field may be used by a client to determine whether it should download a new copy of the lineup so that the local copy reflects any channel moves / adds / changes from the provider.
• "lastDataUpdate" - This field indicates when the last data update was made to the database. The client should cache this field. If the locally cached last data update is the same as the server date, then there is no new information and the client should disconnect.
• "notifications" - String array of global notifications, including system downtime and system status.
• "systemStatus" - contains an array of last updated system status. The "date" field is the "as-of".
• "response" and "code" - indicates whether the request was valid. The client should look for response codes.
• "serverID" - the backend server which processed the request. Used for troubleshooting.

headends

Send: {"request":"PC:60030","object":"headends","action":"get","api":20130107}

The response from the server:

{"response":"OK","code":200,"datetime":"2012-12-20T18:50:30Z","data":[{"headend":"4DTV","Name":"4DTV","Location":"USA"},{"headend":"AFN","Name":"AFN Satellite","Location":"USA"},{"headend":"C-BAND","Name":"C-Band","Location":"USA"},{"headend":"DITV","Name":"DIRECTV","Location":"USA"},{"headend":"ECHOST","Name":"DISH Network","Location":"USA"},{"headend":"FAVE","Name":"FAVE","Location":"USA"},{"headend":"GLOBCST","Name":"Globecast World TV","Location":"USA"},{"headend":"GLOBETV","Name":"MyGlobeTV","Location":"USA"},{"headend":"SKYANGL","Name":"Sky Angel Faith TV","Location":"USA"},{"headend":"FTA","Name":"Free-to-air satellite","Location":"Global"},{"headend":"IL57303","Name":"Comcast Lake Forest/Waukegan","Location":"Lake Forest"},{"headend":"IL61078","Name":"Saddlebrook Farms","Location":"Grayslake"},{"headend":"IL63063","Name":"Comcast McHenry-New","Location":"Mchenry"},{"headend":"IL63463","Name":"Comcast Algonquin/Elgin","Location":"Carpentersville"},{"headend":"IL67050","Name":"AT&T U-verse TV","Location":"Chicago"},{"headend":"DISH602","Name":"DISH Chicago","Location":"Chicago"},{"headend":"DITV602","Name":"DIRECTV Chicago","Location":"Chicago"},{"headend":"PC:60030","Name":"Antenna","Location":"Over-the-air"}]}

The "data" field provides the headend ID and name for the headends that are valid for a location.

If the randhash is included in the request, the server will reply with only the headends that the user has configured:

Send:

{"randhash":"{randhash}","object":"headends","action":"get","api":20130107}

The response from the server:

{"response":"OK","code":200,"datetime":"2012-12-17T20:16:24Z","data":[{"headend":"0005995","Name":"Shaw Direct","Location":"Canada (East) Classic"},{"headend":"DISH561","Name":"DISH Jacksonville","Location":"Jacksonville"},{"headend":"DITV561","Name":"DIRECTV Jacksonville","Location":"Jacksonville"},{"headend":"IL57303","Name":"Comcast Lake Forest/Waukegan","Location":"Lake Forest"}]}

lineups

Provides the mapping of channels for a particular headend. Once initial configuration has been completed, unless the "modified" date in the status request indicates that there has been a change, the client does not need to re-download the lineup.

Send:

{"randhash":"{randhash}","object":"lineups","action":"get","api":20130107,"request":["IL57303","ECHOST"]}

The response from the server:

The server sends you a zip file. Each lineup is a separate file in the zip container.

The file will be named {headendID}.json.zip

The entry will look like:

{"name":"Comcast Lake Forest/Waukegan","location":"Lake Forest","deviceTypes":["X","Analog"],"X":{"map":[{"stationID":74348,"channel":"001"},{"stationID":11299,"channel":"002"} ... ,{"stationID":58912,"channel":"962"},{"stationID":58911,"channel":"963"}]},"Analog":{"map":[{"stationID":11299, "channel":"002"},{"stationID":11848,"channel":"004"},{"stationID":11670,"channel":"005"} ... },{"stationID":16715,"channel":"099"}]},"stationID":[{"name":"AMC","callsign":"AMC","affiliate":"Satellite","broadcaster":{"city":"Jericho","state":"NY","zipcode":"1 1753","country":"United States"},"stationID":10021},{"name":"A & E Network","callsign":"AETV","affiliate":"Satellite","broadcaster":{"city":"New York","state":"NY","zipcode":"10017","country":"United States"},"stationID":10035} ... ,{"name":"beIN Sport En Espanol","callsign":"BEIN2","affiliate":"Satellite","broadcaster":{"city":"Unknown","state":"","zipcode":"00000","country":"Unknown"},"stationID":76943}],"metadata":[{"device":"X","modified":"2012-12-11T22:46:03Z"},{"device":"Analog","modified":"2012-12-11T22:02:21Z"}],"QAM":{"map":[{"virtualChannel":"NULL","channel":"950","qamType":"QAM256","qamFreq":103750000,"qamProgram":201,"stationID":0},{"virtualChannel":"NULL","channel":"951","qamType":"QAM256","qamFreq":103750000,"qamProgram":202,"stationID":0}

The lineup file provides specific information about this particular lineup. The major categories are:

• "name" - The name of the headend.
• "location" - the geolocation of the headend as defined by the provider.
• "devicetypes" - On this headend, what kinds of devices are present? For a cable lineup, "Analog" is any signals which can be received without a set-top-box. "X" is the standard digital cable lineup. If a provider is transitioning from one channel lineup to another, there may be others, such as "L", "R", "D", etc. Each of these are typically used as a "Rebuild" lineup; the provider often can not "flash cut" all subscribers at once, so a phased approach is typically used.
• {devicetypename} -> "map". The correlation of stationID to channel number for this particular device.
• stationID - metadata about a particular provider. In a cable lineup, the "broadcaster" data is used to provide information about the source, which may not be local.
• "metadata" - Information about each {devicetype}; provides a "last modified" field indicating when the last channel move / add / change was performed to this device.
• QAM - if available, will provide a mapping of QAM tuning information for cable TV. As of 2013-01-13, WORK IN PROGRESS.

schedules

Provides the schedules for requested station id's for the next two weeks.

Send:

{"randhash":"{randhash}","object":"schedules","action":"get","api":20130107,"request":["10090","21249"]}

In the above example, the client has requested the schedules for two stationIDs - 10090 and 21249. The server has been tested with thousands of stationIDs in a single request, but you are encouraged to chunk your requests if the client is not able to handle it because of network or CPU/memory considerations.

The client should determine the minimum unique number of stationIDs which it needs to request. For example, if a user has an over-the-air lineup and a cable lineup in their account, then there will be an overlap between those two lineups, because most if not all over-the-air stations will be present in the local cable lineup.

The response from the server:

The server sends you a zip file. Each schedule is a separate file in the zip container. Any zip files received from the server will now include a file called "serverID.txt" indicating which backend server assembled the file.

A schedule file will be named sched_{stationID}.json.txt

Requesting a stationID which is not in any of the user's configured headends will result in a file which contains:

{"response":"ERROR","code":404,"serverID":"AWS-micro.1","message":"This stationID is not in any of your headends.","datetime":"2013-01-09T06:50:34Z"}

A valid schedule file will look like:

{"programID":"EP000044440691","md5":"orJ/LbyODX/+HOuKNAQ4YQ","airDateTime":"2013-01-19T11:30:00Z","duration":1800,"cc":true,"stereo":true,"tvRating":" TVG","netSyndicationSource":"SYND","netSyndicationType":"Off Network"},{"programID":"EP016306630015","md5":"AH0tyG/GCz+5m30pTmCrag","airDateTime":"2013-01-19T12:00:00Z" ,"duration":7200,"cc":true,"stereo":true,"netSyndicationSource":"CBS","netSyndicationType":"Broadcast Network"},{"programID":"SH016033340000","md5":"7U02L4FaGxuMC8/rj/B g8w","airDateTime":"2013-01-19T14:00:00Z","duration":3600,"new":true}

The client should parse the schedule file for each stationID in the .zip file and determine which programs need to be downloaded. If the client has already cached a programID from a previous download and the MD5 of the local programID is the same as what is on the server, then the client does not need to re-download the program.

For certain stationIDs, where there is static or near-static content it is possible that each airDateTime "slot" all point to the same programID.

Consult the table later in this document for a description of the various fields in the schedule.

programs

Once the client has downloaded the schedule and determined which programs it needs to update locally, either because it has not already cached that program, or the MD5 hash of the program has changed (indicating that metadata about the program has changed) the client should make the following request:

Send:

{"randhash":"{randhash}","object":"programs","action":"get","api":20130107,"request":["EP000000060008","EP000000060015", etc]}

NOTE: The server has been tested with over 30,000 programID requests as a single transaction. This may overload the client, so you are encouraged to chunk your requests if necessary.

The client should only request the minimum number of programs required. A program which is being shown on multiple stationIDs will have the same programID and only needs to be downloaded once.

The response from the server:

The server sends you a zip file. Each program id is a separate file in the zip container. Any zip files received from the server will now include a file called "serverID.txt" indicating which backend server assembled the file.

Each individual file will be named {programID}.json.txt

The file will contain information like this:

{"castAndCrew":["Actor:Gorden Kaye","Actor:Carmen Silvera","Actor:Rose Hill","Actor:Vicki Michelle","Actor:Kirsten Cooke"],"seriesDescription":"A cafe owner attempts to repatriate escapees during World War II.","titles":{"title40":"'Allo 'Allo!","title120":"'Allo 'Allo!","title10":"'Allo!","title20":"'Allo 'Allo!","title70":"'Allo 'Allo!"},"genres":["Sitcom"],"originalAirDate":"1987-12-05","descriptions":{"description60":"Von Klink arrests Flick; the men hide batteries in sausages.","descriptionLanguage":"English","alternateDescription255":"Flick is placed under arrest; everyone searches for missing submarine batteries.","alternateDescription100":"Flick is placed under arrest; everyone searches for missing submarine batteries.","description100":"Flick is placed under arrest; everyone searches for missing submarine batteries.","description255":"Flick is placed under arrest; everyone searches for missing submarine batteries.","description40":"Batteries in sausages."},"showType":"Series","metadata":[{"dataSource":"thetvdb","episode":"5","seriesID":"73940","season":"4"}],"programID":"EP000000060020","syndicatedEpisodeNumber":"405","alternateSyndicatedEpisodeNumber":"27","sourceType":"Syndicated","colorCode":"Color","md5":"b+dPVPEDsECNil0kXrCzaA","episodeTitle150":"The Sausages in the Trousers"} Note that a program object does not contain information such as "HDTV" - that is contained in the schedule object, because the same program may be shown in high definition on one particular stationID, but transcoded by the provider into standard definition on another stationID.

Any field names which contain a number indicate the max length of that field and may be used by the client to truncate various fields when being displayed on devices with limited screen space.

The "metadata" field is used as an alternate data source to the "syndicatedEpisodeNumber" and "alternateSyndicatedEpisodeNumber" fields in the data. Those values are provided by the production company for the program, and may or may not correlate to typical season / episode values which most users are accustomed to.

add

headends

Send: {"randhash":"{randhash","object":"headends","action":"add","api":20130107,"request":"ECHOST"}

The response from the server:

{"response":"OK","code":200,"message":"Added headend.","datetime":"2012-12-18T20:21:58Z"}

or

{"response":"ERROR","code":401,"message":"Exceeded number of headends for this account.","datetime":"2012-12-18T20:16:05Z"}

delete

headends

Send:

{"randhash":"{randhash}","object":"headends","action":"delete","api":20130107,"request":"ECHOST"}

The response from the server:

{"response":"OK","code":200,"message":"Deleted headend.","datetime":"2012-12-18T20:23:34Z"}

update

password

Send:

{"request":{"newpassword":"abcdefgh123456789"},"randhash":"fed8ac3d1d14cf3b2e8948393c9f0b73","object":"password","action":"update","api":20130107}

The response from the server: {"response":"OK","code":200,"serverID":"AWS-micro.1","message":"Password updated.","datetime":"2013-01-08T00:10:34Z"}

metadata

The update -> metadata request is used when the provided metadata for a program is incorrect.

The relevant fields in the request:

• "prog_id" - what program are we talking about?
• "current" - what is the current seriesID. If "0", that means that the program should have a seriesID, but doesn't.
• "suggested" - if set to anything other than "0", that means that the program should be changed to "this" value. If suggested is set to "0", that means that the seriesID as presented is totally wrong, and there is no replacement.
• "seriesid". What is the thing that needs to be changed? At this time, "seriesid" is the only thing that is being looked at.
• "source" - what is the source. At this time, "thetvdb" is the only thing being looked at. In the future this may be other things, like URLs.
• "comment" - Up to 1024 characters. Text comment to the reviewer in case additional information is required.

Send: {"request":{"source":"thetvdb","comment":"Please update as soon as possible.","suggested":"71256","current":"0","prog_id":"EP002930532006","field":"seriesid"},"randhash":"f0bb3abd4145942b76b316c5d654047e","object":"metadata","action":"update","api":20130107}

Response from server:

{"response":"OK","code":200,"serverID":"AWS-micro.1","message":"Stored change request.","datetime":"2013-01-08T00:17:01Z"}

The following tables will provide additional information about the various responses from the server. As of 2012-12-31 they are being edited and are in a state of flux.

Field Name	Optional	Description	Notes
Location	N	The headend's geographical location
Name	N	The headend's name
headend	N	The unique id for the headend

Metadata

This data is obtained via URL: get/lineup/<id>; response is GZIP encoded!

Field Name	Optional	Description	Notes
device	N	The name/id of a specific device of a headend	The value here is contained in the DeviceTypes array of a lineup
modified	N	The date this device was last modified upstream	The lineup URL for this device will not have changed since this date; caching possibility

Lineup

Retrieving a lineup will provide a file which contains the following objects:

baselevel:

name: String containing the name of the headend.

location: String containing the geo location of the headend.

deviceTypes: array of strings containing the device designations. Possible values are "Analog" (for a cable lineup, these are the stations which can be tuned without a set top box) and others such as "D", "L", "R", "X". "X" is the typical "set-top-box" lineup / "Digital". If a provider is going to implement a lineup change and can not get all subscribers cut over at once, then they may create a "Rebuild" lineup, and that would then receive a new letter designation.

"metadata": a container which holds a key "modified" with a value which specifies when the last update occurred.

Example: "metadata":[{"device":"X","modified":"2012-12-11T22:46:03Z"},{"device":"Analog","modified":"2012-12-11T22:02:21Z"}]

This information may be used by a client to determine if it should refresh the local copy of a lineup.

"{deviceType}" - provides a container for an object called "map". The map object is an array containing key/value pairs to correlate a stationID and a channel. Example:

"X":{"map":[{"stationID":74348,"channel":"001"},{"stationID":11299,"channel":"002"}]}

deviceType "X" contains a map with two channels. stationID is an integer value. Channel 001 is a string (which can be numerified by the client; string values are used to accommodate satellite channels.)

stationID: a container containing an array of strings which correlates broadcaster metadata to a stationID. A stationID is only specified once, even if the station appears multiple times in the lineup.

Example:

"stationID":[{"name":"AMC","callsign":"AMC","affiliate":"Satellite","broadcaster":{"city":"Jericho","state":"NY","zipcode":"11753","country":"United States"},"stationID":10021}]

stationID 10021 has a name of "AMC", a callsign of "AMC". "broadcaster" contains key/value pairs providing information about this specific broadcaster and where their corporate offices are located.

"QAM": a container holding a map object. The "map" object is an array of key/value pairs.

Example:

"QAM":{"map":[{"virtualChannel":"NULL","channel":"950","qamType":"QAM256","qamFreq":103750000,"qamProgram":201,"stationID":0}

NOTE: Not all lineups will have a QAM object. NOTE: As of 2013-01-15, QAM is still being revised to include the fields which are currently shown as "0".

Field Name	Optional	Description	Notes
DeviceTypes	N	An array of device names contained in this headend's lineup. Example values would be Analog, D, F, L, X, etc. "Analog" would be the list of channels which can be accessed without a set-top-box, "X" is typically a Digital Set Top Box lineup, the others are various Rebuild/Overlay lineups if a provider is not able to flash cut all subscribers to a new headend.	Values here can be used as keys to the channel maps, when necessary (i.e. cable/sat headends)
StationID	N	An array of Station objects, each representing a channel available on this headend	A Station object will appear in each headend to which it belongs, but should only be downloaded once and then shared amongst each headend that needs it
X	Y	A key found in DeviceTypes; this is an object containing various useful info, such as the channel mappings for a headend; typically only found for cable/sat headends and not for OTA; **The actual name of this field will differ based on the keys found in DeviceTypes**For Free-to-air satellite listings, it will contain a list of satellite names.
location	Y	The lineup's location (i.e. city)	Not provided for OTA lineups. For free-to-air satellite, contains the location of the satellite, such as "125.0 W"
metadata	N	An array of objects where each object is a description of specific device in the headend
name	Y	The name of the lineup	Not provided for OTA lineups

Station

Field Name	Optional	Description	Notes
affiliate	N	A station's parent affiliate
atsc_major	Y	The ATSC major number for OTA tuning of this station. An analog-only station will have atsc_major and atsc_minor as "0"	Only provided for OTA channels; absent for others (i.e. cable only/pay channels)
atsc_minor	Y	The ATSC minor number for OTA tuning of this station at the headend's location	Only provided for OTA channels; absent for others
broadcaster-city	N	The city this station broadcasts from
broadcaster-country	N	The country this station broadcast's from
broadcaster-state	N	The state/province this station broadcasts from
broadcaster-zipcode	N	The zip/postal code of the station's broadcast location
callsign	N	The station's uniquely assigned callsign
name	N	The station's full name
qam_frequency	Y		"559750000"
qam_modulation	Y	Modulation type	"QAM256"
qam_program	Y	Used to select a particular stream.	"23"
qam_virtualchannel	Y	What the station display's to users.	"2.1"
stationid	N	The station's unique (listings) id; i.e. data direct unique id
uhf_vhf	Y	The station's physical UHF/VHF channel number	Only present for stations who broadcast OTA

Schedule

Fields are only included if they are relevant. Any fields not in the resulting file should be assumed to be boolean "false".

Field Name	Optional	Description	Notes
3d	N	Is this airing in 3D?
air_datetime	N	ISO-8601 formatted GMT start time and date.
cable_in_the_classroom	N	Is this airing available on CitC?
cc	N	Is this airing closed captioned?
datatype	N	Type of object; always 'schedule'
dialog_rating	N	Does this airing contain strong dialog?
dolby	N	Type of HD sound for this airing.	"Dolby", "DD" - Dolby Digital, "DD5.1" - Dolby Digital 5.1, "DSS" - Dolby Surround
dubbed	N	Is the program dubbed?
dubbed_language	N		Example: "Spanish"
duration	N	The length of this airing, in seconds; currently encoded as a string	End time must be calculated: start + duration = end_time
dvs	N	Does this airing provide descriptive video?
educational	N	Broadcaster designated program as Educational / Informative
enhanced	N
fv_rating	N	Does this airing contain fantasy violence?
hdtv	N	Is this airing in HD?
joined_in_progress	N	Was this airing joined in progress?
lang_rating	N	Does this airing contain suggestive language?
left_in_progress	N	Will this airing be left in progress?
letterbox	N	Is this airing letterboxed?
live_tape_delay	N	Is this airing live or on a tape delay?	Empty string for none or one of 'Live|Tape|Delay'
net_syn_source	N	Originating Source	Example: FOX
net_syn_type	N	Broadcast Network, First Run Syndication, Off Network
new	N	Is this airing new?
num_parts	N	Total number of parts; currently encoded as string	Will be 0 if not necessary for any given airing
part_num	N	Which part number is this? encoded as a string	Will be 0 if not necessary for any given airing
premiere_finale	N	Is this airing a premiere or finale?	Empty string if neither else one of Premiere|Season Premiere|Season Finale|Series Premiere|Series Finale
prog_id	N	Unique id to obtain program object for this airing	EP*, SP*, SH*, MV*
sap	Y	Is SAP available for this airing?	Only present if there is SAP available
sap_language	Y	Which alternate language is available?	Example: "Spanish"
sex_rating	N	Does airing contain sexually suggestive content?
stereo	N	Is this airing in stereo sound?
subject_to_blackout	N	Is this airing subject to blackout?
subtitled	Y	Is this airing subtitled?	Not always present
subtitled_language	Y	What language are the subtitles in?	Example: "English"
time_approximate	N	Is the duration approximate?
tv_rating	N	TV rating for this airing	TVY, TVY7, TVG, TVPG, TV14, TVMA
violence_rating	N	Does this airing contain violence?

Program

Any fields not present in the resulting data should be assumed to be boolean "false" or not applicable.

Field Name	Optional	Description	Notes
advisories	Y	Array of advisories which may not fit other categories.	"Adult Situations", "Brief Nudity"
alt_syn_epi_num	N	Alternate syndicated episode number	Sometimes it is a production code, or some other internal code designated by the provider. Use the "metadata" array for true season / episode information.
alt_title	N	Alternate title
cast_and_crew	Y	Array of cast & crew members for this program	Only present when there is data available
color_code	N	Color code for this program	B&W, Color, Colorized, Color and B&W
datatype	N	The type of this object; always 'program'
descr	N	The program's full description
descr_[70/40/20/10]	N	Shorter forms of the description.
descr_lang_id	N	The language used in the description texts
epi_title	N	aka the subtitle of the episode.	May contain team vs. team information for sport events.
game_datetime	Y	ISO 8601 formatted original game date and time as reported by the league / station (in GMT).	"2012-10-13T01:00:00Z". Only present for SP* events.
genres	Y	Array of genres for this program	Only present when there is data available. Example: "Anime", "Comedy", "Horror"
holiday	Y	Is this program associated with a holiday?	"Christmas", "Can. Thanksgiving"
made_for_tv	N	Is this a made for tv movie?
md5	N	An MD5 hash of the object	Computed based on the raw data import. The client should maintain a local mapping of program id and md5 to make determinations if a particular program needs to be updated. Each schedule object will provide a program id and md5.
metadata	Y	An array of values which specify metadata about this program.	[{"seriesid":"73940","episode":"1","datasource":"thetvdb","season":"3"},{"url":"http://en.wikipedia.org/wiki/%27Allo_%27Allo!_(series_2)","datasource":"wikipedia"}] See table below for additional information.
modified	N	The date and time this object was last modified upstream; yyyy-MM-dd HH:mm:ss
mpaa_rating	Y	The MPAA rating for this program	Only present for movie type programs (MV*)
orig_air_date	N	The original air date for this program	Always present but is 0000-00-00 if not available/applicable; use this for "new" determination typically
orig_country	N	The program's country of origin
orig_studio	Y	The program's originating studio	For MV* only??
prog_id	N	The unique id	Use this to map programs with schedule objects, etc.
run_time	Y	Runtime; hh:mm:ss	Only present for MV* objects; a movie's run time may be different than its duration due to commercials.
series_description	Y	The generic description for the series.	"Homer and Marge Simpson raise Bart, Lisa and baby Maggie."
show_type	N	Type of show	Series, Paid Programming, Serial, Special, Miniseries
source_type	N	Source type	Block, Local, Network, Syndicated
star_rating	Y	Star rating of a movie	Only present for MV*; empty-0 stars/not available, "*", "*+", "**", "**+", "***", "***+", "****"
syn_epi_num	N	Episode number	Sometimes it is a production code, or some other internal code designated by the provider. Use the "metadata" array for true season / episode information.
title	N	Program's full title
title_[70/40/20/10]	N	Shorter versions of the program's title.
year	Y	A movie's year of release	Will only be present for MV*

Program Metadata

Contained within the program data.

datasource:thetvdb

Field	Description	Notes
season	Season number	Optional
episode		Optional
seriesid		If an exact match between a particular episode and metadata can't be made, but the seriesid is known, then it will be provided.