-
Notifications
You must be signed in to change notification settings - Fork 5
API 20140530
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.
API 20140530 is end-of-life as of 2015-07-01, and no further schedule / lineup updates will be made. You must switch to API 20141201 if you would like to continue receiving data.
See (http://forums.schedulesdirect.org/viewtopic.php?f=17&t=2676) for details.
NOTE: our contract with our upstream provider limits us to providing data for individual use only. 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 20140530.
The server implements a RESTful interface.
There are multiple tools which can assist if you're implementing a REST client; two good ones are the Postman helper in Chrome and JSONlint at http://jsonlint.org
You can also use the mfdb-json PHP scripts at https://github.com/SchedulesDirect/mfdb-json as a starting point.
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) for a headend 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 their 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 is 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 need sent to you. 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.
- 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 PUT function to add that headend to their account at Schedules Direct. By default, a user may have 4 headends 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 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 - 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.
- Process the schedules; each schedule for each station id will contain at least 12 days of data, unless you have specifically requested fewer days: 2, 4 and 13 days are acceptable values.
- 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 programID requests, but the response may overload the client. Therefore 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 a token.
- 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, 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.
- Honor the nextScheduled time in the status object; if your client connects during server-side data processing, the nextScheduled time will be "closer", however reconnecting while server-side data is being processed will not result in newer data.
- 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. 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; at most there will be 4. 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.)
The following examples give some pointers on how to use the Chrome POSTMan client to step through the tasks that your program must perform in order to use the service.
###Determine if the client is the correct version
Your client may make a request and query the server to determine if it is running the latest client.
GET https://json.schedulesdirect.org/20140530/version/{clientname}
Token: Not Required
For example:
GET https://json.schedulesdirect.org/20140530/version/mfdb-json
Response:
{
"response": "OK",
"code": 0,
"client": "mfdb-json",
"version": "0.11",
"serverID": "20140530.t2.1",
"datetime": "2014-09-22T19:11:38Z"
}
Your code could then compare the version in the response with an internal version and then prompt the user with what they'd like to do next.
Error Response:
{
"response": "UNKNOWN_CLIENT",
"code": 1005,
"serverID": "20140530.t2.1",
"message": "Did not recognize the submitted client.",
"datetime": "2014-09-22T19:39:52Z"
}
NOTE:Developers, please contact grabber@schedulesdirect.org and provide the clientname string and the version that you'd like the server to reply with.
###Obtain the list of headends in a postal code
GET https://json.schedulesdirect.org/20140530/headends?country=USA&postalcode=60030
Token: Required
Response:
{
"60030": {
"type": "Over-the-Air",
"location": "60030",
"lineups": [
{
"name": "Antenna",
"uri": "/20140530/lineups/USA-OTA-60030"
}
]
},
"4DTV": {
"type": "Satellite",
"location": "USA",
"lineups": [
{
"name": "4DTV",
"uri": "/20140530/lineups/USA-4DTV-DEFAULT"
}
]
},
"AFN": {
"type": "Satellite",
"location": "USA",
"lineups": [
{
"name": "AFN Satellite",
"uri": "/20140530/lineups/USA-AFN-DEFAULT"
}
]
},
"C-BAND": {
"type": "Satellite",
"location": "USA",
"lineups": [
{
"name": "C-Band",
"uri": "/20140530/lineup/USA-C-BAND-DEFAULT"
}
]
},
"DISH602": {
"type": "Satellite",
"location": "Chicago",
"lineups": [
{
"name": "DISH Chicago",
"uri": "/20140530/lineups/USA-DISH602-DEFAULT"
}
]
},
"DITV": {
"type": "Satellite",
"location": "USA",
"lineups": [
{
"name": "DIRECTV",
"uri": "/20140530/lineups/USA-DITV-DEFAULT"
}
]
},
"DITV602": {
"type": "Satellite",
"location": "Chicago",
"lineups": [
{
"name": "DIRECTV Chicago",
"uri": "/20140530/lineups/USA-DITV602-DEFAULT"
}
]
},
"ECHOST": {
"type": "Satellite",
"location": "USA",
"lineups": [
{
"name": "DISH Network",
"uri": "/20140530/lineups/USA-ECHOST-DEFAULT"
}
]
},
"GLOBCST": {
"type": "Satellite",
"location": "USA",
"lineups": [
{
"name": "Globecast World TV",
"uri": "/20140530/lineups/USA-GLOBCST-DEFAULT"
}
]
},
"GLRYSTR": {
"type": "Satellite",
"location": "USA",
"lineups": [
{
"name": "GLRYSTR",
"uri": "/20140530/lineups/USA-GLRYSTR-DEFAULT"
}
]
},
"IL57303": {
"type": "Cable",
"location": "Lake Forest",
"lineups": [
{
"name": "Comcast Waukegan/Lake Forest Area - Digital",
"uri": "/20140530/lineups/USA-IL57303-X"
}
]
},
"IL61078": {
"type": "Cable",
"location": "Grayslake",
"lineups": [
{
"name": "Saddlebrook Farms - Cable",
"uri": "/20140530/lineups/USA-IL61078-DEFAULT"
}
]
},
"IL63063": {
"type": "Cable",
"location": "Mchenry",
"lineups": [
{
"name": "Comcast McHenry & Fox Areas - Digital",
"uri": "/20140530/lineups/USA-IL63063-X"
}
]
},
"IL63463": {
"type": "Cable",
"location": "Carpentersville",
"lineups": [
{
"name": "Comcast Algonquin/Elgin Areas - Digital",
"uri": "/20140530/lineups/USA-IL63463-X"
}
]
},
"IL67050": {
"type": "Cable",
"location": "Chicago",
"lineups": [
{
"name": "AT&T U-verse TV - Digital",
"uri": "/20140530/lineups/USA-IL67050-X"
}
]
},
"RELAYTV": {
"type": "Satellite",
"location": "USA",
"lineups": [
{
"name": "RELAYTV",
"uri": "/20140530/lineups/USA-RELAYTV-DEFAULT"
}
]
}
}
Use the lineup names obtained from the GET /headends that are appropriate for your postal code.
Token: Required
The command follows this format:
PUT /lineups/{COUNTRY}-{LINEUP}-{DEVICE}
So, to add IL57303:X in the United States:
PUT https://json.schedulesdirect.org/20140530/lineups/USA-IL57303-X
Response:
{
"response": "OK",
"code": 0,
"serverID": "AWS-SD-web.1",
"message": "Added lineup.",
"changesRemaining": 254,
"datetime": "2014-05-19T20:16:01Z"
}
Error response:
{"response":"INVALID_LINEUP","code":2105,"serverID":"20140530.t2.1","message":"The
lineup you submitted doesn't exist.","datetime":"2014-09-20T03:34:25Z"}
###List the lineups a user has added to their account.
Token: Required
GET https://json.schedulesdirect.org/20140530/lineups
Response:
{
"serverID": "20140530.2",
"datetime": "2014-12-31T17:07:20Z",
"lineups": [
{
"lineup": "BRA-0003288-X",
"name": "Nossa TV Brasileira - Digital",
"type": "Cable",
"location": "Brazil",
"uri": "/20140530/lineups/BRA-0003288-X"
},
{
"lineup": "GBR-0001172-DEFAULT",
"name": "BSkyB - England",
"type": "Satellite",
"location": "United Kingdom",
"uri": "/20140530/lineups/GBR-0001172-DEFAULT"
},
{
"lineup": "GBR-OTA-W2",
"name": "Local",
"type": "Antenna",
"location": "W2",
"uri": "/20140530/lineups/GBR-OTA-W2"
},
{
"lineup": "KNA-0000050-DEFAULT",
"name": "The Cable-St. Kitts/Cable TV of Nevis - Cable",
"type": "Cable",
"location": "Basseterre",
"uri": "/20140530/lineups/KNA-0000050-DEFAULT"
},
{
"lineup": "USA-IL57303-X",
"name": "Comcast Waukegan/Lake Forest Area - Digital",
"type": "Cable",
"location": "Lake Forest",
"uri": "/20140530/lineups/USA-IL57303-X"
},
{
"lineup": "USA-MI58783-QAM",
"name": "WOW Detroit - QAM",
"type": "QAM",
"location": "Plymouth",
"uri": "/20140530/lineups/USA-MI58783-QAM"
},
{
"lineup": "USA-WI61859-DEFAULT",
"name": "DELETED LINEUP",
"type": "Deleted",
"location": "X",
"uri": "/20140530/lineups/USA-WI61859-DEFAULT",
"isDeleted": true
}
]
}
NOTE: If a lineup has been marked as deleted at the server, both the status and the subscribed lineups will indicate "isDeleted" as TRUE. Your application should use this to notify the user that their lineup may no longer be valid.
Token: Required
DELETE /lineups/{COUNTRY}-{LINEUP}-{DEVICE}
Example:
DELETE https://json.schedulesdirect.org/20140530/lineups/USA-IL57303-X
Response:
{
"response": "OK",
"code": 0,
"serverID": "AWS-SD-web.1",
"message": "Deleted lineup.",
"changesRemaining": "254",
"datetime": "2014-05-19T20:18:20Z"
}
Token: Required
GET /lineups/{COUNTRY}-{LINEUP}-{DEVICE}
Example:
GET https://json.schedulesdirect.org/20140530/lineups/USA-IL57303-X
Response:
{
"map": [
{
"stationID": "74348",
"channel": "001"
},
{
"stationID": "11299",
"channel": "002"
},
{
"stationID": "12475",
"channel": "003"
},
{
"stationID": "11848",
"channel": "004"
},
{
"stationID": "11670",
"channel": "005"
},
{
"stationID": "11461",
"channel": "006"
},
{
"stationID": "11653",
"channel": "007"
},
etc.
After the "map" section comes the station information:
"stations": [
{
"callsign": "OND",
"name": "XFINITY On Demand",
"broadcastLanguage": "en",
"descriptionLanguage": "en",
"stationID": "74348"
},
{
"callsign": "WBBM",
"name": "WBBM",
"broadcastLanguage": "en",
"descriptionLanguage": "en",
"logo": {
"URL": "https://s3.amazonaws.com/schedulesdirect-API20140530/assets/s10098_h3_aa.png",
"height": 270,
"width": 360,
"md5": "68713effdd9df195833a56"
},
"stationID": "11299"
},
{
"callsign": "WJYS",
"name": "WJYS",
"broadcastLanguage": "en",
"descriptionLanguage": "en",
"stationID": "12475"
},
etc.
If a station is commercial-free, then that will be indicated in the data as the isCommercialFree attribute; the default is "FALSE" and is therefore not included to reduce the size of the data.
{
"callsign": "WMVS",
"isCommercialFree": true,
"name": "WMVS",
"broadcastLanguage": "en",
"descriptionLanguage": "en",
"logo": {
"URL": "https://s3.amazonaws.com/schedulesdirect-API20140530/assets/s11039_h3_aa.png",
"height": 270,
"width": 360,
"md5": "b54e65c3384cc904c90124"
},
"stationID": "11701"
},
The final piece of information is metadata:
"metadata": {
"lineup": "USA-IL57303-X",
"modified": "2014-11-10T17:56:33Z",
"transport": "Cable"
}
NOTE: Your code must not assume that the "map" section is first in the data, or that the "metadata" is last.
Please see QAM for details on how QAM lineup mappings should be processed.
POST https://json.schedulesdirect.org/20140530/programs
Token: Required
The body of the request will have the programIDs you are requesting.
Your client must send an Accept-Encoding that has "deflate,gzip" in it, even though the response will be gzip'ed. This is due to an implementation bug in 20140530 which will be fixed in 20141201.
NOTE: No more than 5000 programIDs in a single request.
["EP000000060003", "EP000000510142"]
The response will look like:
{"programID":"EP000000060003","titles":[{"title120":"'Allo 'Allo!"}],"eventDetails":{"subType":"Series"},"descriptions":{"description1000":[{"descriptionLanguage":"en","description":"A disguised British Intelligence officer is sent to help the airmen."}]},"originalAirDate":"1985-11-04","genres":["Sitcom"],"episodeTitle150":"The Poloceman Cometh","metadata":[{"Tribune":{"season":2,"episode":3}}],"cast":[{"personId":"383774","nameId":"392649","name":"Gorden Kaye","role":"Actor","billingOrder":"01"},{"personId":"246840","nameId":"250387","name":"Carmen Silvera","role":"Actor","billingOrder":"02"},{"personId":"376955","nameId":"385830","name":"Rose Hill","role":"Actor","billingOrder":"03"},{"personId":"259773","nameId":"263340","name":"Vicki Michelle","role":"Actor","billingOrder":"04"},{"personId":"353113","nameId":"361987","name":"Kirsten Cooke","role":"Actor","billingOrder":"05"},{"personId":"77787","nameId":"77787","name":"Richard Marner","role":"Actor","billingOrder":"06"},{"personId":"230921","nameId":"234193","name":"Guy Siner","role":"Actor","billingOrder":"07"},{"personId":"374934","nameId":"383809","name":"Kim Hartman","role":"Actor","billingOrder":"08"},{"personId":"369151","nameId":"378026","name":"Richard Gibson","role":"Actor","billingOrder":"09"},{"personId":"343690","nameId":"352564","name":"Arthur Bostrom","role":"Actor","billingOrder":"10"},{"personId":"352557","nameId":"361431","name":"John D. Collins","role":"Actor","billingOrder":"11"},{"personId":"605275","nameId":"627734","name":"Nicholas Frankau","role":"Actor","billingOrder":"12"},{"personId":"373394","nameId":"382269","name":"Jack Haig","role":"Actor","billingOrder":"13"}],"crew":[{"personId":"354407","nameId":"363281","name":"David Croft","role":"Director","billingOrder":"01"},{"personId":"354407","nameId":"363281","name":"David Croft","role":"Writer","billingOrder":"02"},{"personId":"105145","nameId":"105145","name":"Jeremy Lloyd","role":"Writer","billingOrder":"03"}],"showType":"Series","hasImageArtwork":true,"md5":"Jo5NKxoo44xRvBCAq8QT2A"}
{"programID":"EP000000510142","titles":[{"title120":"A Different World"}],"eventDetails":{"subType":"Series"},"descriptions":{"description1000":[{"descriptionLanguage":"en","description":"Whitley and Dwayne tell new students about their honeymoon in Los Angeles."}]},"originalAirDate":"1992-09-24","genres":["Sitcom"],"episodeTitle150":"Honeymoon in L.A.","metadata":[{"Tribune":{"season":6,"episode":1}}],"cast":[{"personId":"700","nameId":"700","name":"Jasmine Guy","role":"Actor","billingOrder":"01"},{"personId":"729","nameId":"729","name":"Kadeem Hardison","role":"Actor","billingOrder":"02"},{"personId":"120","nameId":"120","name":"Darryl M. Bell","role":"Actor","billingOrder":"03"},{"personId":"1729","nameId":"1729","name":"Cree Summer","role":"Actor","billingOrder":"04"},{"personId":"217","nameId":"217","name":"Charnele Brown","role":"Actor","billingOrder":"05"},{"personId":"1811","nameId":"1811","name":"Glynn Turman","role":"Actor","billingOrder":"06"},{"personId":"1232","nameId":"1232","name":"Lou Myers","role":"Actor","billingOrder":"07"},{"personId":"1363","nameId":"1363","name":"Jada Pinkett","role":"Guest Star","billingOrder":"08"},{"personId":"222967","nameId":"225536","name":"Ajai Sanders","role":"Guest Star","billingOrder":"09"},{"personId":"181744","nameId":"183292","name":"Karen Malina White","role":"Guest Star","billingOrder":"10"},{"personId":"305017","nameId":"318897","name":"Patrick Y. Malone","role":"Guest Star","billingOrder":"11"},{"personId":"9841","nameId":"9841","name":"Bumper Robinson","role":"Guest Star","billingOrder":"12"},{"personId":"426422","nameId":"435297","name":"Sister Souljah","role":"Guest Star","billingOrder":"13"},{"personId":"25","nameId":"25","name":"Debbie Allen","role":"Guest Star","billingOrder":"14"},{"personId":"668","nameId":"668","name":"Gilbert Gottfried","role":"Guest Star","billingOrder":"15"}],"showType":"Series","hasImageArtwork":true,"md5":"P5kz0QmCeYxIA+yL0H4DWw"}
Each line is a separate JSON object, however the entire response is not JSON. Taking the first response and feeding it into pro.jsonlint.com:
{
"programID": "EP000000060003",
"titles": [
{
"title120": "'Allo 'Allo!"
}
],
"eventDetails": {
"subType": "Series"
},
"descriptions": {
"description1000": [
{
"descriptionLanguage": "en",
"description": "A disguised British Intelligence officer is sent to help the airmen."
}
]
},
"originalAirDate": "1985-11-04",
"genres": [
"Sitcom"
],
"episodeTitle150": "The Poloceman Cometh",
"metadata": [
{
"Tribune": {
"season": 2,
"episode": 3
}
}
],
"cast": [
{
"personId": "383774",
"nameId": "392649",
"name": "Gorden Kaye",
"role": "Actor",
"billingOrder": "01"
},
{
"personId": "246840",
"nameId": "250387",
"name": "Carmen Silvera",
"role": "Actor",
"billingOrder": "02"
},
{
"personId": "376955",
"nameId": "385830",
"name": "Rose Hill",
"role": "Actor",
"billingOrder": "03"
},
{
"personId": "259773",
"nameId": "263340",
"name": "Vicki Michelle",
"role": "Actor",
"billingOrder": "04"
},
{
"personId": "353113",
"nameId": "361987",
"name": "Kirsten Cooke",
"role": "Actor",
"billingOrder": "05"
},
{
"personId": "77787",
"nameId": "77787",
"name": "Richard Marner",
"role": "Actor",
"billingOrder": "06"
},
{
"personId": "230921",
"nameId": "234193",
"name": "Guy Siner",
"role": "Actor",
"billingOrder": "07"
},
{
"personId": "374934",
"nameId": "383809",
"name": "Kim Hartman",
"role": "Actor",
"billingOrder": "08"
},
{
"personId": "369151",
"nameId": "378026",
"name": "Richard Gibson",
"role": "Actor",
"billingOrder": "09"
},
{
"personId": "343690",
"nameId": "352564",
"name": "Arthur Bostrom",
"role": "Actor",
"billingOrder": "10"
},
{
"personId": "352557",
"nameId": "361431",
"name": "John D. Collins",
"role": "Actor",
"billingOrder": "11"
},
{
"personId": "605275",
"nameId": "627734",
"name": "Nicholas Frankau",
"role": "Actor",
"billingOrder": "12"
},
{
"personId": "373394",
"nameId": "382269",
"name": "Jack Haig",
"role": "Actor",
"billingOrder": "13"
}
],
"crew": [
{
"personId": "354407",
"nameId": "363281",
"name": "David Croft",
"role": "Director",
"billingOrder": "01"
},
{
"personId": "354407",
"nameId": "363281",
"name": "David Croft",
"role": "Writer",
"billingOrder": "02"
},
{
"personId": "105145",
"nameId": "105145",
"name": "Jeremy Lloyd",
"role": "Writer",
"billingOrder": "03"
}
],
"showType": "Series",
"hasImageArtwork": true,
"md5": "Jo5NKxoo44xRvBCAq8QT2A"
}
Your client should maintain a cached copy of the program data; if the MD5 for a programID differs then your client will know that it should re-download the program data.
See Program Response for details on the fields.
See Retrieving Images for information on how your client can retrieve images.
###Download the schedules for stationIDs
POST https://json.schedulesdirect.org/20140530/schedules
Token: Required
The body of the request will have the stationIDs that you are requesting schedules for.
NOTE: No more than 5000 schedule IDs in a single request.
[{"stationID":"10002", "days":13}, {"stationID":"20454","days":13}]
NOTE: you may request 2, 4 or 13 days of data.
Will return something which looks like this:
{"stationID":"10002","programs":[{"programID":"SH003712850000","md5":"LiAma3Y25JBWkrJvbNDvTg","airDateTime":"2014-05-02T00:00:00Z","duration":3600},{"programID":"SH006701200000","md5":"WI1BR8w4nPmXOVwe\/qK2xA","airDateTime":"2014-05-02T01:00:00Z","duration":7200,"liveTapeDelay":"Live","new":true},{"programID":"SH012546070000","md5":"vQ7tHUkfCvzyLY2OoG6rrQ","airDateTime":"2014-05-02T03:00:00Z","duration":3600},{"programID":"SH006701200000","md5":"WI1BR8w4nPmXOVwe\/qK2xA","airDateTime":"2014-05-02T04:00:00Z","duration":3600},{"programID":"SH017588780000","md5":"98wfRh+5cV741AFgFZlm6A","airDateTime":"2014-05-02T05:00:00Z","duration":3600},{"programID":"SH006701200000","md5":"WI1BR8w4nPmXOVwe\/qK2xA","airDateTime":"2014-05-02T06:00:00Z","duration":7200,"liveTapeDelay":"Live","new":true},{"programID":"SH005532720000","md5":"O2f14xmm2a9FB6VWvO7q8w","airDateTime":"2014-05-
02T08:00:00Z","duration":3600}
{"programID":"SH000006800000","md5":"XFG2oYyaxHLeGFnIYADtNA","airDateTime":"2014-05-04T00:00:00Z","duration":1800,"audioProperties":["cc","stereo"]}}
{"stationID":"20454","programs":[{"programID":"EP009311820166","md5":"dA+SfzzL0H7wwiw9ZIux1w","airDateTime":"2014-05-02T00:00:00Z","duration":1860,"contentRating":[{"body":"USA Parental Rating","code":"TVPG"}],"contentAdvisory":{"USA Parental Rating":["Language","Dialog"]},"syndication":{"source":"CBS","type":"Broadcast Network"},"new":true,"audioProperties":["cc","stereo","DD 5.1"],"videoProperties":["hdtv"]},{"programID":"EP017398410024","md5":"DWgiUeVMH10G1Uj+Pukj\/A","airDateTime":"2014-05-02T00:31:00Z","duration":1800,"contentRating":[{"body":"USA Parental Rating","code":"TVPG"}],"contentAdvisory":{"USA Parental Rating":["Language","Dialog"]},"syndication":{"source":"CBS","type":"Broadcast Network"},"new":true,"audioProperties":["cc","stereo","DD 5.1"],"videoProperties":["hdtv"]}
(etc)
See Schedule Response for information regarding the fields in the schedule.
###Download the MD5 and lastModified for stationIDs
POST https://json.schedulesdirect.org/20140530/schedules/md5
Token: Required
The body of the request will have the stationIDs that you are requesting. This function is useful to determine whether a particular stationID has an updated schedule; schedules are typically updated 4 times per day, 7 days per week. If a schedule has been updated, the MD5 and lastModified for that stationID will be updated. Using this function, your client can determine (through use of a local cache) if it needs to download a new schedule.
NOTE: No more than 5000 stationIDs in a single request.
[{"stationID":"10036", "days":13}, {"stationID":"10091", "days":2}, {"stationID":"10091", "days":4}, {"stationID":"10091", "days":13}]
Which will return the following response:
{
"10036": [
{
"days": 13,
"md5": "StiEox/4JyAHD4lUvrMCIQ",
"modified": "2014-09-18T20:59:07Z"
}
],
"10091": [
{
"days": 2,
"md5": "Ei1DujpwycpFBPXK6fXzjw",
"modified": "2014-09-18T20:59:07Z"
},
{
"days": 4,
"md5": "+Yqb0vg+0ZeMm7Jttbapcw",
"modified": "2014-09-18T20:59:08Z"
},
{
"days": 13,
"md5": "x9PdBejLYqJmytIHePhWlw",
"modified": "2014-09-18T20:59:08Z"
}
]
}
The above example is artificial in the sense that a client would typically only download one particular "days" value.
A bandwidth-limited client might be programmed to only request 2 days if they're on a cellular connection, but 4 days if they're on WiFi, while an always-on server may request 13 days.
###Delete a system message
DELETE /messages/{messageID}
Deletes non-system status messages from the status response.
###Download graphics, channel logos, banners
GET /assets/{uri}
Images, fanart, logos, etc will have a URI in the JSON response. If the URI is complete, it will point to Amazon S3, in which case your application should pull the image directly from Amazon. If the URI is incomplete (no http:// for example), then send the request to Schedules Direct. Your application will then receive a 303 redirect.
See Retrieving Images for information on how your client can retrieve images.
The system may respond to a request and send back an error code.
| Response | Internal Code | Error |
|---|---|---|
| 0 | OK | OK |
| 1001 | INVALID_JSON | Unable to decode JSON |
| 1002 | DEFLATE_REQUIRED | Did not receive Accept-Encoding: deflate in request. |
| 1004 | TOKEN_MISSING | Token required but not provided in request header. |
| 2000 | UNSUPPORTED_COMMAND | Unsupported command |
| 2001 | REQUIRED_ACTION_MISSING | Request is missing an action to take. |
| 2002 | REQUIRED_REQUEST_MISSING | Did not receive request. |
| 2004 | REQUIRED_PARAMETER_MISSING:COUNTRY | In order to search for lineups, you must supply a 3-letter country parameter. |
| 2005 | REQUIRED_PARAMETER_MISSING:POSTALCODE | In order to search for lineups, you must supply a postal code parameter. |
| 2006 | REQUIRED_PARAMETER_MISSING:MSGID | In order to delete a message you must supply the messageID. |
| 2050 | INVALID_PARAMETER:COUNTRY | The COUNTRY parameter must be ISO-3166-1 alpha 3. See http://en.wikipedia.org/wiki/ISO_3166-1_alpha-3 |
| 2051 | INVALID_PARAMETER:POSTALCODE | The POSTALCODE parameter must be valid for the country you are searching. Post message to http://forums.schedulesdirect.org/viewforum.php?f=6 if you are having issues. |
| 2052 | INVALID_PARAMETER:FETCHTYPE | You didn't provide a fetchtype I know how to handle. |
| 2100 | DUPLICATE_LINEUP | Lineup already in account. |
| 2101 | LINEUP_NOT_FOUND | Lineup not in account. Add lineup to account before requesting mapping. |
| 2102 | UNKNOWN_LINEUP | Invalid lineup requested. Check your COUNTRY / POSTALCODE combination for validity. |
| 2103 | INVALID_LINEUP_DELETE | Delete of lineup not in account. |
| 2104 | LINEUP_WRONG_FORMAT | Lineup must be formatted COUNTRY-LINEUP-DEVICE or COUNTRY-OTA-POSTALCODE |
| 2105 | INVALID_LINEUP | The lineup you submitted doesn't exist. |
| 2106 | LINEUP_DELETED | The lineup you requested has been deleted from the server. |
| 2107 | LINEUP_QUEUED | The lineup is being generated on the server. Please retry. |
| 2108 | INVALID_COUNTRY | The country you requested is either mis-typed or does not have valid data. |
| 2200 | STATIONID_NOT_FOUND | The stationID you requested is not in any of your lineups. |
| 3000 | SERVICE_OFFLINE | Server offline for maintenance. |
| 4001 | ACCOUNT_EXPIRED | Account expired. |
| 4002 | INVALID_HASH | Password hash must be lowercase 40 character sha1_hex of password. |
| 4003 | INVALID_USER | Invalid username or password. |
| 4004 | ACCOUNT_LOCKOUT | Too many login failures. Locked for 15 minutes. |
| 4100 | MAX_LINEUP_CHANGES_REACHED | Exceeded maximum number of lineup changes for today. |
| 4101 | MAX_LINEUPS | Exceeded number of lineups for this account. |
| 4102 | NO_LINEUPS | No lineups have been added to this account. |
| 5000 | IMAGE_NOT_FOUND | Could not find requested image. Post message to http://forums.schedulesdirect.org/viewforum.php?f=6 if you are having issues. |
| 6000 | INVALID_PROGRAMID | Could not find requested programID. Permanent failure. |
| 6001 | PROGRAMID_QUEUED | ProgramID should exist at the server, but doesn't. The server will regenerate the JSON for the program, so your application should retry. |
| 7000 | SCHEDULE_QUEUED | The schedule you requested has been queued for generation but is not yet ready for download. Retry. The response will indicate a "retryTime" parameter. Your code should honor this time in order to give the server enough time to generate the schedule. |
| 7100 | SCHEDULE_NOT_FOUND | The schedule you requested should be available. Post message to http://forums.schedulesdirect.org/viewforum.php?f=6 |
| 9999 | HCF | Unknown error. Open support ticket. |