DRAFT: Delta between API 20140530 and 20141201

rkulagow
SD Staff
Posts: 915
Joined: Tue Aug 14, 2007 3:15 pm

DRAFT: Delta between API 20140530 and 20141201

Post by rkulagow » Wed Jan 21, 2015 8:19 am

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.

rkulagow
SD Staff
Posts: 915
Joined: Tue Aug 14, 2007 3:15 pm

Re: DRAFT: Delta between API 20140530 and 20141201

Post by rkulagow » Thu Feb 19, 2015 10:59 pm

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.

rkulagow
SD Staff
Posts: 915
Joined: Tue Aug 14, 2007 3:15 pm

Re: DRAFT: Delta between API 20140530 and 20141201

Post by rkulagow » Thu Feb 26, 2015 2:12 pm

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

rkulagow
SD Staff
Posts: 915
Joined: Tue Aug 14, 2007 3:15 pm

Re: DRAFT: Delta between API 20140530 and 20141201

Post by rkulagow » Mon Mar 02, 2015 2:08 pm

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.

rkulagow
SD Staff
Posts: 915
Joined: Tue Aug 14, 2007 3:15 pm

Re: DRAFT: Delta between API 20140530 and 20141201

Post by rkulagow » Fri Mar 06, 2015 1:14 pm

Sending an empty "date" array will also send all available data.

rkulagow
SD Staff
Posts: 915
Joined: Tue Aug 14, 2007 3:15 pm

Re: DRAFT: Delta between API 20140530 and 20141201

Post by rkulagow » Fri Mar 06, 2015 3:06 pm

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.

rkulagow
SD Staff
Posts: 915
Joined: Tue Aug 14, 2007 3:15 pm

Re: DRAFT: Delta between API 20140530 and 20141201

Post by rkulagow » Mon Mar 09, 2015 8:59 am

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.

rkulagow
SD Staff
Posts: 915
Joined: Tue Aug 14, 2007 3:15 pm

Re: DRAFT: Delta between API 20140530 and 20141201

Post by rkulagow » Mon Mar 09, 2015 8:58 pm

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.

rkulagow
SD Staff
Posts: 915
Joined: Tue Aug 14, 2007 3:15 pm

Re: DRAFT: Delta between API 20140530 and 20141201

Post by rkulagow » Thu Mar 12, 2015 7:34 pm

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.

rkulagow
SD Staff
Posts: 915
Joined: Tue Aug 14, 2007 3:15 pm

Re: DRAFT: Delta between API 20140530 and 20141201

Post by rkulagow » Mon Mar 16, 2015 7:32 am

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.

Post Reply