Page 1 of 6

DRAFT: Delta between API 20140530 and 20141201

Posted: Wed Jan 21, 2015 8:19 am
by rkulagow
Progams:
- New qualifier: "Parental Advisory"

Schedules:
- Client request for MD5 for a stationID will return the MD5 of each day from "today" through the end of data. (Typically 12 to 13 days). The client will then be able to request the schedule for a particular date rather than only having 2, 4 or 13 day options. [2015-01-21: Still being implemented]

Countries:
Lineups and schedules for France and Germany.

Re: DRAFT: Delta between API 20140530 and 20141201

Posted: Thu Feb 19, 2015 10:59 pm
by rkulagow
Number of days of data increased; up to 30 days of schedule data will be available, with the caveat the data further into the future is more subject to change.

Re: DRAFT: Delta between API 20140530 and 20141201

Posted: Thu Feb 26, 2015 2:12 pm
by rkulagow
Updated documentation for the schedules and schedules MD5 at
https://github.com/SchedulesDirect/JSON ... stationids

Updated lineup response: (stations is now an associative array with the stationID as the key)
https://github.com/SchedulesDirect/JSON ... r-a-lineup

Re: DRAFT: Delta between API 20140530 and 20141201

Posted: Mon Mar 02, 2015 2:08 pm
by rkulagow
Updated example of fetching schedule MD5. Including a "date" element with an array of dates will send the MD5 of just those dates for that stationID. Not including the "date" element will send all MD5 from "today" through the last date available.

Re: DRAFT: Delta between API 20140530 and 20141201

Posted: Fri Mar 06, 2015 1:14 pm
by rkulagow
Sending an empty "date" array will also send all available data.

Re: DRAFT: Delta between API 20140530 and 20141201

Posted: Fri Mar 06, 2015 3:06 pm
by rkulagow
The "nextSuggestedConnectTime" is now deprecated and will not be sent in the "account" portion of the status response. There are no blackout times on the server because there are multiple data loads throughout the day, so your client MAY connect at any time.

However, your client SHOULD use the "lastDataUpdate" field to decide whether it should request MD5s for stations.

Re: DRAFT: Delta between API 20140530 and 20141201

Posted: Mon Mar 09, 2015 8:59 am
by rkulagow
The systemStatus response is an array consisting of date, status and message fields.

Your code MUST be able to handle the following "status" types:

Online - no issues.
Degraded - something is broken; the message text will indicate what is wrong. (May be expanded to indicate which call is faulty, such as GET /status. TBD)
Offline - system is down for maintenance.

Code: Select all

"systemStatus": [
        {
            "date": "2015-03-09T00:00:00Z",
            "status": "Degraded",
            "message": "Adding a lineup through the API is currently not functioning properly."
        },
        {
            "date": "2015-03-09T00:00:01Z",
            "status": "Online",
            "message": "Adding a lineup through the API is currently not functioning properly."
        }
    ],
Yes, the above example is contradictory.

Re: DRAFT: Delta between API 20140530 and 20141201

Posted: Mon Mar 09, 2015 8:58 pm
by rkulagow
The response received for querying the headends in a postal code is under development to try to make it simpler for various parsers to use directly.

Please see
viewtopic.php?f=17&t=2559

and provide your feedback if the headends response works for you.

Re: DRAFT: Delta between API 20140530 and 20141201

Posted: Thu Mar 12, 2015 7:34 pm
by rkulagow
The station response inside a lineup will now look like this:

Code: Select all

"stations": [
        {
            "stationID": "19567",
            "name": "KCBSDT (KCBS-DT)",
            "callsign": "KCBSDT",
            "affiliate": "CBS",
            "broadcastLanguage": [
                "en"
            ],
            "descriptionLanguage": [
                "en"
            ],
            "broadcaster": {
                "city": "Studio City",
                "state": "CA",
                "postalcode": "91604",
                "country": "United States"
            },
            "logo": {
                "URL": "https://s3.amazonaws.com/schedulesdirect/assets/stationLogos/s10098_h3_aa.png",
                "height": 270,
                "width": 360,
                "md5": "68713effdd9df195833a56"
            }
        },
Stations will no longer use the stationID as an associative array, so your code will need to traverse the elements.

broadcastLanguage and descriptionLanguage are now arrays of values. If there is more than one language, they will be sorted in ascending alphabetical order; therefore, your client should not attach any significance to the order.

The "broadcaster" element will no longer contain "Unknown" values. If the information isn't known, it won't be included.

Re: DRAFT: Delta between API 20140530 and 20141201

Posted: Mon Mar 16, 2015 7:32 am
by rkulagow
A new call is now available.

GET /available

Token: Not required.

Currently returns:
["COUNTRIES"]

GET /available/countries

Token: Not required.

Currently returns:

Code: Select all

{
    "North America": [
        {
            "fullName": "United States",
            "shortName": "USA",
            "postalCodeExample": "12345",
            "postalCode": "/\\d{5}/"
        },
        {
            "fullName": "Canada",
            "shortName": "CAN",
            "postalCodeExample": "K1A0B1",
            "postalCode": "/[A-Z]{1}[\\d]{1}[A-Z]{1}[\\d]{1}[A-Z]{1}[\\d]{1}/gm"
        }
    ],
    "Europe": [
        {
            "fullName": "Denmark",
            "shortName": "DNK",
            "postalCodeExample": "9260",
            "postalCode": "/\\d{4}/"
        },
        {
            "fullName": "Finland",
            "shortName": "FIN",
            "postalCodeExample": "91980",
            "postalCode": "/\\d{5}/"
        },
        {
            "fullName": "France",
            "shortName": "FRA",
            "postalCodeExample": "38800",
            "postalCode": "/\\d{5}/"
        },
        {
            "fullName": "Germany",
            "shortName": "DEU",
            "postalCodeExample": "14050",
            "postalCode": "/\\d{5}/"
        },
        {
            "fullName": "Great Britain",
            "shortName": "GBR",
            "postalCodeExample": "CF31",
            "postalCode": "/[A-Z]{1,2}\\d{1,2}/"
        },
        {
            "fullName": "Sweden",
            "shortName": "SWE",
            "postalCodeExample": "10005",
            "postalCode": "/\\d{5}/"
        }
    ],
    "Latin America": [
        {
            "fullName": "Argentina",
            "shortName": "ARG",
            "postalCodeExample": "A4190",
            "postalCode": "/[A-Z]\\d{4}/"
        },
        {
            "fullName": "Belize",
            "shortName": "BLZ",
            "postalCodeExample": "BZ",
            "postalCode": "/BZ/",
            "onePostalCode": true
        },
        {
            "fullName": "Brazil",
            "shortName": "BRA",
            "postalCodeExample": "01419",
            "postalCode": "/\\d{5}/"
        },
        {
            "fullName": "Chile",
            "shortName": "CHL",
            "postalCodeExample": "1000000",
            "postalCode": "/\\d{7}/"
        },
        {
            "fullName": "Columbia",
            "shortName": "COL",
            "postalCodeExample": "CO",
            "postalCode": "/CO/",
            "onePostalCode": true
        },
        {
            "fullName": "Costa Rica",
            "shortName": "CRI",
            "postalCodeExample": "10101",
            "postalCode": "/\\d{5}/"
        },
        {
            "fullName": "Ecuador",
            "shortName": "ECU",
            "postalCodeExample": "170950",
            "postalCode": "/\\d{6}/"
        },
        {
            "fullName": "Guatemala",
            "shortName": "GTM",
            "postalCodeExample": "01001",
            "postalCode": "/\\d{5}/"
        },
        {
            "fullName": "Guyana",
            "shortName": "GUY",
            "postalCodeExample": "GY",
            "postalCode": "/GY/",
            "onePostalCode": true
        },
        {
            "fullName": "Honduras",
            "shortName": "HND",
            "postalCodeExample": "HN",
            "postalCode": "/HN/",
            "onePostalCode": true
        },
        {
            "fullName": "Mexico",
            "shortName": "MEX",
            "postalCodeExample": "11500",
            "postalCode": "/\\d{5}/"
        },
        {
            "fullName": "Panama",
            "shortName": "PAN",
            "postalCodeExample": "PA",
            "postalCode": "/PA/",
            "onePostalCode": true
        },
        {
            "fullName": "Peru",
            "shortName": "PER",
            "postalCodeExample": "23006",
            "postalCode": "/\\d{5}/"
        },
        {
            "fullName": "Uruguay",
            "shortName": "URY",
            "postalCodeExample": "11000",
            "postalCode": "/\\d{5}/"
        },
        {
            "fullName": "Venezuela",
            "shortName": "VEN",
            "postalCodeExample": "1010",
            "postalCode": "/\\d{4}/"
        }
    ],
    "Caribbean": [
        {
            "fullName": "Anguila",
            "shortName": "AIA",
            "postalCodeExample": "AI-2640",
            "postalCode": "/AI-2640/",
            "onePostalCode": true
        },
        {
            "fullName": "Antigua/Barbuda",
            "shortName": "ATG",
            "postalCodeExample": "AG",
            "postalCode": "/AG/",
            "onePostalCode": true
        },
        {
            "fullName": "Aruba",
            "shortName": "ABW",
            "postalCodeExample": "AW",
            "postalCode": "/AW/",
            "onePostalCode": true
        },
        {
            "fullName": "Bahamas",
            "shortName": "BHS",
            "postalCodeExample": "BS",
            "postalCode": "/BS/",
            "onePostalCode": true
        },
        {
            "fullName": "Barbados",
            "shortName": "BRB",
            "postalCodeExample": "BB14001",
            "postalCode": "/BB\\d{5}/"
        },
        {
            "fullName": "Bermuda",
            "shortName": "BMU",
            "postalCodeExample": "CR01",
            "postalCode": "/[A-Z]{2}\\d{2}/"
        },
        {
            "fullName": "Bonaire, Saba, St. Eustatius",
            "shortName": "BES",
            "postalCodeExample": "BQ",
            "postalCode": "/BQ/",
            "onePostalCode": true
        },
        {
            "fullName": "British Virgin Islands",
            "shortName": "VGB",
            "postalCodeExample": "VG1110",
            "postalCode": "/VG\\d{4}/"
        },
        {
            "fullName": "Cayman Islands",
            "shortName": "CYM",
            "postalCodeExample": "KY1-0001",
            "postalCode": "/KY\\d{1}-\\d{4}/"
        },
        {
            "fullName": "Curacao",
            "shortName": "CUW",
            "postalCodeExample": "CW",
            "postalCode": "/CW/",
            "onePostalCode": true
        },
        {
            "fullName": "Dominica",
            "shortName": "DMA",
            "postalCodeExample": "DM",
            "postalCode": "/DM/",
            "onePostalCode": true
        },
        {
            "fullName": "Dominican Republic",
            "shortName": "DOM",
            "postalCodeExample": "10101",
            "postalCode": "/\\d{5}/"
        },
        {
            "fullName": "Grenada",
            "shortName": "GRD",
            "postalCodeExample": "GW",
            "postalCode": "/GD/",
            "onePostalCode": true
        },
        {
            "fullName": "Jamaica",
            "shortName": "JAM",
            "postalCodeExample": "JMAAW01",
            "postalCode": "/JM[A-Z]{3}\\d{2}/"
        },
        {
            "fullName": "Puerto Rico",
            "shortName": "PRI",
            "postalCodeExample": "00601",
            "postalCode": "/\\d{5}/"
        },
        {
            "fullName": "Saint Martin",
            "shortName": "MAF",
            "postalCodeExample": "97150",
            "postalCode": "/97150/",
            "onePostalCode": true
        },
        {
            "fullName": "Saint Vincent / Grenadines",
            "shortName": "VCT",
            "postalCodeExample": "VC0100",
            "postalCode": "/VC\\d{4}/"
        },
        {
            "fullName": "St. Kitts and Nevis",
            "shortName": "KNA",
            "postalCodeExample": "KN",
            "postalCode": "/KN/",
            "onePostalCode": true
        },
        {
            "fullName": "St. Lucia",
            "shortName": "LCA",
            "postalCodeExample": "LC",
            "postalCode": "/LC/",
            "onePostalCode": true
        },
        {
            "fullName": "Trinidad and Tobago",
            "shortName": "TTO",
            "postalCodeExample": "TT",
            "postalCode": "/TT/",
            "onePostalCode": true
        },
        {
            "fullName": "Turks and Caicos",
            "shortName": "TCA",
            "postalCodeExample": "TKCA1ZZ",
            "postalCode": "/TKCA1ZZ/",
            "onePostalCode": true
        }
    ]
}
"shortName" is the 3-letter code that the server is parsing when you request a lineup.
If an entry contains a "onePostalCode" element, that means that there is only one valid postal code for this region.
"postalCode" is a RegEx that your code COULD use to sanity check the user's entry prior to sending it to the server.

Send suggested renaming for elements if the above isn't clear.

Future support will expand the list of available data; once Freesat is integrated the "/available" call will be updated. Work in progress.