Documentation

http://cache.kexp.org provides a number of REST web services that provide information about KEXP programming.

Introduction

All of the web services support REST, which means that you can access a service just by typing a URL into your browser. You can also easily access the services from a program by issuing a web request to the service URL, or by using the jQuery $.ajax method from Javascript in a web page.

Requests

All services support the GET http verb. If a service requires parameters, they should be added to the URL query string. For example, to find out what song was plaing on November 8, 2011 at noon, you could make this request:

http://cache.kexp.org/cache/plays?startTime=2011-11-8T04:00

Note that the time specified is 4:00am, because all date/time parameters are in universal (UTC) time, and KEXP in Seattle is eight hours behind UTC.

Many request parameters are optional, and can be omitted entirely from the query string. For example, http://cache.kexp.org/cache/plays (without the startTime) returns the play airing at the current time.

All date/time parameters must be specified in UTC. The required format for date/time parameters is 2011-11-9T17:05 (year-month-dayThour:minute)

Response Formats

The services return either JSON or XML formatted data. There are two different URLs for each service, one for JSON and one for XML. For example:

All of the URLs follow this convention. JSON is the default. To get XML, add /xml after /cache in the URL.

When accessing the cache web services from a web page, you must use a JSONP request to overcome cross-domain restrictions. This is very easy to do with jQuery:

$.ajax({ url: 'http://cache.kexp.org/cache/programs', dataType: 'jsonp', jsonpCallback: 'programs', cache: true, success: function (result) { ... }, error: function (xhr, status, error) { ... } }

Note the inclusion of jsonpCallback: 'programs' and cache: true. Setting jsonpCallback to a specific name improves caching of results. Since caching is done on the server, using the naming convention jsonpCallback: 'requestName' improves performance for all users.

You may also issue a JSONP request manually by adding a callback=functionName parameter to the query string (jQuery does this automatically for dataType jsonp).

Response Content

KEXP web service responses are generally a list of items that match the request. In addition to the list, a number of properties are included:

Property Name Description
Count The number of items returned
IsStale Normally false, indicating that the returned data is current. If true, the cache does not contain up-to-date programming information.
PlayDate Generally this represents the startTime of the request. In some responses, PlayDate has a specialized meaning.
ResponseDate The date/time that the web server created the response. If the response is cached by the server, this date may be the same for a subsequent request.
PersistenceDate The date/time that the cache originally acquired the data that is being returned.
Hosts / Plays / Programs / Shows The list of items returned.

The Services

Hosts

Returns the hosts for the specified channel. If no channel is included in the request, hosts for all channels are returned.

Parameters

Name Value Required Default
channel 1 or 2 (1 = Seattle, 2 = New York) No Data for all channels returned

Sample response

{ "Count":2,"ResponseDate":"\/Date(1320963388875)\/","PersistenceDate":"\/Date(1320958589000)\/", "Hosts":[{"Uri":"http:\/\/services.kexp.org\/rest\/hosts\/296","Name":"Abe Beeson","ImageUri":"https:\/\/kexpstorage.blob.core.windows.net\/images\/hosts\/111328","User":null,"IsActive":true,"ShowHosts":null}, {"Uri":"http:\/\/services.kexp.org\/rest\/hosts\/11","Name":"Amanda Wilde","ImageUri":null,"User":null,"IsActive":false,"ShowHosts":null}] }

Plays

Returns the latest play for the specified channel. If no channel is included in the request, the latest play for any channel is returned.

Note: If no play is cached for the current time, the most recently cached play is returned, and the IsStale property of the response is set to true.

Parameters

Name Value Required Default
channel 1 or 2 (1 = Seattle, 2 = New York) No Data for all channels returned

Sample response

{ "Count":1,"IsStale":false,"PlayDate":"\/Date(1320965160000)\/","ResponseDate":"\/Date(1320965315368)\/","PersistenceDate":"\/Date(1320965311000)\/", "Plays":[{"Uri":"http:\/\/services.kexp.org\/rest\/plays\/1467732","Type":4,"RotationType":null,"IsRequest":false,"AirDate":"\/Date(1320965160000)\/","IsDeleted":false,"CreatedDate":"\/Date(1320965276130)\/","UpdatedDate":"\/Date(1320965276130)\/", "Show":{"__type":"Show:http:\/\/services.kexp.org\/","Uri":"http:\/\/services.kexp.org\/rest\/shows\/53138","AirDate":"\/Date(1320962400000)\/","Tagline":"The Afternoon Show: loves you!","IsDeleted":false,"CreatedDate":"\/Date(1320962686000)\/","UpdatedDate":"\/Date(1320962686000)\/", "Program":{"__type":"Program:http:\/\/services.kexp.org\/","Uri":"http:\/\/services.kexp.org\/rest\/programs\/1","Name":"Variety Mix","Tags":"Rock,Eclectic", "Channel":{"Uri":"http:\/\/services.kexp.org\/rest\/channels\/1"}, "Shows":null}, "ShowHosts":null}, "Artist":null,"Release":null,"Track":null,"Label":null,"ReleaseEvent":null,"Comments":[],"Opinions":null}] }

Returns the most recent plays aired since the specified time for the specified channel. If no time is specified, all plays aired in the last two hours are returned. If no channel is included in the request, the recent plays for all channels are returned.

Note: If no plays are cached for the last two hours, the most recently cached plays are returned, and the IsStale property of the response is set to true.

Parameters

Name Value Required Default
since Earliest airdate to retrieve No Data for last two hours returned
channel 1 or 2 (1 = Seattle, 2 = New York) No Data for all channels returned

Sample response

{ "Count":2,"IsStale":false,"PlayDate":"\/Date(1320972949000)\/","ResponseDate":"\/Date(1320973076335)\/","PersistenceDate":"\/Date(1320973074000)\/", "Plays":[{"Uri":"http:\/\/services.kexp.org\/rest\/plays\/1467828","Type":1,"RotationType":1,"IsRequest":false,"AirDate":"\/Date(1320972949000)\/","IsDeleted":false,"CreatedDate":"\/Date(1320972958963)\/","UpdatedDate":"\/Date(1320972958963)\/", "Show":{"__type":"Show:http:\/\/services.kexp.org\/","Uri":"http:\/\/services.kexp.org\/rest\/shows\/52763","AirDate":"\/Date(1316113320000)\/","Tagline":"The Morning Show LIVE from Iceland","IsDeleted":false,"CreatedDate":"\/Date(1316113739850)\/","UpdatedDate":"\/Date(1316113739850)\/", "Program":{"__type":"Program:http:\/\/services.kexp.org\/","Uri":"http:\/\/services.kexp.org\/rest\/programs\/52","Name":"Test Program","Tags":"Rock,Eclectic", "Channel":{"Uri":"http:\/\/services.kexp.org\/rest\/channels\/3"}, "Shows":null}, "ShowHosts":null}, "Artist":{"__type":"Artist:http:\/\/services.kexp.org\/","Uri":"http:\/\/services.kexp.org\/rest\/artists\/46038","MusicBrainzId":"e754303f-655e-41f4-9dbe-b11b5614bd3d","Name":"Charalambides","IsLocal":false,"Releases":null,"Plays":null,"TrackArtists":null,"MetadataSource":4}, "Release":{"__type":"Release:http:\/\/services.kexp.org\/","Uri":"http:\/\/services.kexp.org\/rest\/releases\/186754","MusicBrainzId":"ff6e494f-29c7-4d3d-aef3-0c7c85b65a68","Name":"Exile","AmazonId":null,"LargeImageUri":null,"SmallImageUri":null,"IsPurchasable":true, "Artist":{"Uri":"http:\/\/services.kexp.org\/rest\/artists\/46038"}, "ReleaseEvents":null,"ReleaseTracks":null,"TablesOfContents":null,"MetadataSource":4}, "Track":{"__type":"Track:http:\/\/services.kexp.org\/","Uri":"http:\/\/services.kexp.org\/rest\/tracks\/903573","MusicBrainzId":null,"Name":"Pity Pity Me","Plays":null,"ReleaseTracks":null,"TrackArtists":null,"MetadataSource":4}, "Label":{"__type":"Label:http:\/\/services.kexp.org\/","Uri":"http:\/\/services.kexp.org\/rest\/labels\/142","MusicBrainzId":"4536e738-6350-4cae-af70-79d56d106c45","Name":"Kranky","Country":null,"ReleaseEvents":null,"MetadataSource":4}, "ReleaseEvent":{"__type":"ReleaseEvent:http:\/\/services.kexp.org\/","Uri":"http:\/\/services.kexp.org\/rest\/releaseevents\/238896","BarCode":null,"CatalogNumber":"KRANK 158","Country":"US", "Date":{"Year":2011,"Month":10,"Day":3}, "Label":{"Uri":"http:\/\/services.kexp.org\/rest\/labels\/142"}, "Release":{"Uri":"http:\/\/services.kexp.org\/rest\/releases\/186754"}, "ReleaseFormat":14}, "Comments":[], "Opinions":null}] }

Returns the plays that have changed since the specified date/time for the specified channel. If no time is specified, all play updates during the last two hours are returned. If no channel is included in the request, the play updates for all channels are returned.

Note: The returned PlayDate is the latest updated date, or the value of the since parameter if there are no updates. This allows successive calls to recentPlayUpdates, with each call using the PlayDate returned by the last call as the since parameter.

Note: If no plays are cached for the last two hours, the most recently cached play updates are returned, and the IsStale property of the response is set to true.

Parameters

Name Value Required Default
since Earliest update date to retrieve No Data for last two hours returned
channel 1 or 2 (1 = Seattle, 2 = New York) No Data for all channels returned

Sample response

{ "Count":2,"IsStale":false,"PlayDate":"\/Date(1321033592677)\/","ResponseDate":"\/Date(1321033904051)\/","PersistenceDate":"\/Date(1321033902000)\/", "Plays":[{"Uri":"http:\/\/services.kexp.org\/rest\/plays\/1468218","Type":2,"RotationType":1,"IsRequest":false,"AirDate":"\/Date(1321033566000)\/","IsDeleted":false,"CreatedDate":"\/Date(1321033592677)\/","UpdatedDate":"\/Date(1321033592677)\/", "Show":{"__type":"Show:http:\/\/services.kexp.org\/","Uri":"http:\/\/services.kexp.org\/rest\/shows\/53142","AirDate":"\/Date(1321020000000)\/","Tagline":"The Morning Show","IsDeleted":false,"CreatedDate":"\/Date(1321020073750)\/","UpdatedDate":"\/Date(1321020073750)\/", "Program":{"__type":"Program:http:\/\/services.kexp.org\/","Uri":"http:\/\/services.kexp.org\/rest\/programs\/1","Name":"Variety Mix","Tags":"Rock,Eclectic", "Channel":{"Uri":"http:\/\/services.kexp.org\/rest\/channels\/1"}, "Shows":null}, "ShowHosts":null}, "Artist":{"__type":"Artist:http:\/\/services.kexp.org\/","Uri":"http:\/\/services.kexp.org\/rest\/artists\/109260","MusicBrainzId":null,"Name":"Keep Shelly in Athens","IsLocal":false,"Releases":null,"Plays":null,"TrackArtists":null,"MetadataSource":1}, "Release":{"__type":"Release:http:\/\/services.kexp.org\/","Uri":"http:\/\/services.kexp.org\/rest\/releases\/186797","MusicBrainzId":null,"Name":"LIVE on KEXP (11\/11\/11)","AmazonId":null,"LargeImageUri":null,"SmallImageUri":null,"IsPurchasable":false, "Artist":{"Uri":"http:\/\/services.kexp.org\/rest\/artists\/109260"}, "ReleaseEvents":null,"ReleaseTracks":null,"TablesOfContents":null,"MetadataSource":1}, "Track":{"__type":"Track:http:\/\/services.kexp.org\/","Uri":"http:\/\/services.kexp.org\/rest\/tracks\/903769","MusicBrainzId":null,"Name":"Sour Own Dream","Plays":null,"ReleaseTracks":null,"TrackArtists":null,"MetadataSource":1}, "Label":{"__type":"Label:http:\/\/services.kexp.org\/","Uri":"http:\/\/services.kexp.org\/rest\/labels\/37438","MusicBrainzId":null,"Name":"KEXP","Country":null,"ReleaseEvents":null,"MetadataSource":1}, "ReleaseEvent":{"__type":"ReleaseEvent:http:\/\/services.kexp.org\/","Uri":"http:\/\/services.kexp.org\/rest\/releaseevents\/238950","BarCode":null,"CatalogNumber":null,"Country":null, "Date":{"Year":2011,"Month":null,"Day":null}, "Label":{"Uri":"http:\/\/services.kexp.org\/rest\/labels\/37438"}, "Release":{"Uri":"http:\/\/services.kexp.org\/rest\/releases\/186797"}, "ReleaseFormat":1}, "Comments":[{"__type":"PlayComment:http:\/\/services.kexp.org\/","Uri":"http:\/\/services.kexp.org\/rest\/comments\/533447","Text":"http:\/\/www.facebook.com\/keepshellyinathens","IsDeleted":false,"CreatedDate":"\/Date(1321033811363)\/","UpdatedDate":"\/Date(1321033811363)\/", "User":{"__type":"User:http:\/\/services.kexp.org\/","Uri":"http:\/\/services.kexp.org\/rest\/users\/22","UserKey":null,"DisplayName":"John Richards","Comments":null,"Opinions":null}, "Play":null}], "Opinions":null}, {"Uri":"http:\/\/services.kexp.org\/rest\/plays\/1468217","Type":2,"RotationType":1,"IsRequest":false,"AirDate":"\/Date(1321033384000)\/","IsDeleted":false,"CreatedDate":"\/Date(1321033439847)\/","UpdatedDate":"\/Date(1321033439847)\/", "Show":{"__type":"Show:http:\/\/services.kexp.org\/","Uri":"http:\/\/services.kexp.org\/rest\/shows\/53142","AirDate":"\/Date(1321020000000)\/","Tagline":"The Morning Show","IsDeleted":false,"CreatedDate":"\/Date(1321020073750)\/","UpdatedDate":"\/Date(1321020073750)\/", "Program":{"__type":"Program:http:\/\/services.kexp.org\/","Uri":"http:\/\/services.kexp.org\/rest\/programs\/1","Name":"Variety Mix","Tags":"Rock,Eclectic", "Channel":{"Uri":"http:\/\/services.kexp.org\/rest\/channels\/1"}, "Shows":null}, "ShowHosts":null}, "Artist":{"__type":"Artist:http:\/\/services.kexp.org\/","Uri":"http:\/\/services.kexp.org\/rest\/artists\/109260","MusicBrainzId":null,"Name":"Keep Shelly in Athens","IsLocal":false,"Releases":null,"Plays":null,"TrackArtists":null,"MetadataSource":1}, "Release":{"__type":"Release:http:\/\/services.kexp.org\/","Uri":"http:\/\/services.kexp.org\/rest\/releases\/186797","MusicBrainzId":null,"Name":"LIVE on KEXP (11\/11\/11)","AmazonId":null,"LargeImageUri":null,"SmallImageUri":null,"IsPurchasable":false, "Artist":{"Uri":"http:\/\/services.kexp.org\/rest\/artists\/109260"}, "ReleaseEvents":null,"ReleaseTracks":null,"TablesOfContents":null,"MetadataSource":1}, "Track":{"__type":"Track:http:\/\/services.kexp.org\/","Uri":"http:\/\/services.kexp.org\/rest\/tracks\/903768","MusicBrainzId":null,"Name":"Struggle with Yourself","Plays":null,"ReleaseTracks":null,"TrackArtists":null,"MetadataSource":1}, "Label":{"__type":"Label:http:\/\/services.kexp.org\/","Uri":"http:\/\/services.kexp.org\/rest\/labels\/37438","MusicBrainzId":null,"Name":"KEXP","Country":null,"ReleaseEvents":null,"MetadataSource":1}, "ReleaseEvent":{"__type":"ReleaseEvent:http:\/\/services.kexp.org\/","Uri":"http:\/\/services.kexp.org\/rest\/releaseevents\/238950","BarCode":null,"CatalogNumber":null,"Country":null, "Date":{"Year":2011,"Month":null,"Day":null}, "Label":{"Uri":"http:\/\/services.kexp.org\/rest\/labels\/37438"}, "Release":{"Uri":"http:\/\/services.kexp.org\/rest\/releases\/186797"}, "ReleaseFormat":1}, "Comments":[{"__type":"PlayComment:http:\/\/services.kexp.org\/","Uri":"http:\/\/services.kexp.org\/rest\/comments\/533446","Text":"http:\/\/keepshellyinathens.blogspot.com\/","IsDeleted":false,"CreatedDate":"\/Date(1321033618207)\/","UpdatedDate":"\/Date(1321033618207)\/", "User":{"__type":"User:http:\/\/services.kexp.org\/","Uri":"http:\/\/services.kexp.org\/rest\/users\/22","UserKey":null,"DisplayName":"John Richards","Comments":null,"Opinions":null}, "Play":null}], "Opinions":null}] }

Returns the plays that aired between the start and end date/times, inclusive, for the specified channel. If no start time is specified, the current time is assumed. If no end time is specified, the start time is used as the end time (so omitting both returns the currently airing play). If no channel is included in the request, the plays for all channels are returned.

Parameters

Name Value Required Default
startTime Earliest airdate to retrieve No Current date/time
endTime Lateest airdate to retrieve No startTime (current date/time if both omitted)
channel 1 or 2 (1 = Seattle, 2 = New York) No Data for all channels returned

Sample response

{ "Count":2,"IsStale":false,"PlayDate":"\/Date(1321033592677)\/","ResponseDate":"\/Date(1321033904051)\/","PersistenceDate":"\/Date(1321033902000)\/", "Plays":[{"Uri":"http:\/\/services.kexp.org\/rest\/plays\/1468218","Type":2,"RotationType":1,"IsRequest":false,"AirDate":"\/Date(1321033566000)\/","IsDeleted":false,"CreatedDate":"\/Date(1321033592677)\/","UpdatedDate":"\/Date(1321033592677)\/", "Show":{"__type":"Show:http:\/\/services.kexp.org\/","Uri":"http:\/\/services.kexp.org\/rest\/shows\/53142","AirDate":"\/Date(1321020000000)\/","Tagline":"The Morning Show","IsDeleted":false,"CreatedDate":"\/Date(1321020073750)\/","UpdatedDate":"\/Date(1321020073750)\/", "Program":{"__type":"Program:http:\/\/services.kexp.org\/","Uri":"http:\/\/services.kexp.org\/rest\/programs\/1","Name":"Variety Mix","Tags":"Rock,Eclectic", "Channel":{"Uri":"http:\/\/services.kexp.org\/rest\/channels\/1"}, "Shows":null}, "ShowHosts":null}, "Artist":{"__type":"Artist:http:\/\/services.kexp.org\/","Uri":"http:\/\/services.kexp.org\/rest\/artists\/109260","MusicBrainzId":null,"Name":"Keep Shelly in Athens","IsLocal":false,"Releases":null,"Plays":null,"TrackArtists":null,"MetadataSource":1}, "Release":{"__type":"Release:http:\/\/services.kexp.org\/","Uri":"http:\/\/services.kexp.org\/rest\/releases\/186797","MusicBrainzId":null,"Name":"LIVE on KEXP (11\/11\/11)","AmazonId":null,"LargeImageUri":null,"SmallImageUri":null,"IsPurchasable":false, "Artist":{"Uri":"http:\/\/services.kexp.org\/rest\/artists\/109260"}, "ReleaseEvents":null,"ReleaseTracks":null,"TablesOfContents":null,"MetadataSource":1}, "Track":{"__type":"Track:http:\/\/services.kexp.org\/","Uri":"http:\/\/services.kexp.org\/rest\/tracks\/903769","MusicBrainzId":null,"Name":"Sour Own Dream","Plays":null,"ReleaseTracks":null,"TrackArtists":null,"MetadataSource":1}, "Label":{"__type":"Label:http:\/\/services.kexp.org\/","Uri":"http:\/\/services.kexp.org\/rest\/labels\/37438","MusicBrainzId":null,"Name":"KEXP","Country":null,"ReleaseEvents":null,"MetadataSource":1}, "ReleaseEvent":{"__type":"ReleaseEvent:http:\/\/services.kexp.org\/","Uri":"http:\/\/services.kexp.org\/rest\/releaseevents\/238950","BarCode":null,"CatalogNumber":null,"Country":null, "Date":{"Year":2011,"Month":null,"Day":null}, "Label":{"Uri":"http:\/\/services.kexp.org\/rest\/labels\/37438"}, "Release":{"Uri":"http:\/\/services.kexp.org\/rest\/releases\/186797"}, "ReleaseFormat":1}, "Comments":[{"__type":"PlayComment:http:\/\/services.kexp.org\/","Uri":"http:\/\/services.kexp.org\/rest\/comments\/533447","Text":"http:\/\/www.facebook.com\/keepshellyinathens","IsDeleted":false,"CreatedDate":"\/Date(1321033811363)\/","UpdatedDate":"\/Date(1321033811363)\/", "User":{"__type":"User:http:\/\/services.kexp.org\/","Uri":"http:\/\/services.kexp.org\/rest\/users\/22","UserKey":null,"DisplayName":"John Richards","Comments":null,"Opinions":null}, "Play":null}], "Opinions":null}, {"Uri":"http:\/\/services.kexp.org\/rest\/plays\/1468217","Type":2,"RotationType":1,"IsRequest":false,"AirDate":"\/Date(1321033384000)\/","IsDeleted":false,"CreatedDate":"\/Date(1321033439847)\/","UpdatedDate":"\/Date(1321033439847)\/", "Show":{"__type":"Show:http:\/\/services.kexp.org\/","Uri":"http:\/\/services.kexp.org\/rest\/shows\/53142","AirDate":"\/Date(1321020000000)\/","Tagline":"The Morning Show","IsDeleted":false,"CreatedDate":"\/Date(1321020073750)\/","UpdatedDate":"\/Date(1321020073750)\/", "Program":{"__type":"Program:http:\/\/services.kexp.org\/","Uri":"http:\/\/services.kexp.org\/rest\/programs\/1","Name":"Variety Mix","Tags":"Rock,Eclectic", "Channel":{"Uri":"http:\/\/services.kexp.org\/rest\/channels\/1"}, "Shows":null}, "ShowHosts":null}, "Artist":{"__type":"Artist:http:\/\/services.kexp.org\/","Uri":"http:\/\/services.kexp.org\/rest\/artists\/109260","MusicBrainzId":null,"Name":"Keep Shelly in Athens","IsLocal":false,"Releases":null,"Plays":null,"TrackArtists":null,"MetadataSource":1}, "Release":{"__type":"Release:http:\/\/services.kexp.org\/","Uri":"http:\/\/services.kexp.org\/rest\/releases\/186797","MusicBrainzId":null,"Name":"LIVE on KEXP (11\/11\/11)","AmazonId":null,"LargeImageUri":null,"SmallImageUri":null,"IsPurchasable":false, "Artist":{"Uri":"http:\/\/services.kexp.org\/rest\/artists\/109260"}, "ReleaseEvents":null,"ReleaseTracks":null,"TablesOfContents":null,"MetadataSource":1}, "Track":{"__type":"Track:http:\/\/services.kexp.org\/","Uri":"http:\/\/services.kexp.org\/rest\/tracks\/903768","MusicBrainzId":null,"Name":"Struggle with Yourself","Plays":null,"ReleaseTracks":null,"TrackArtists":null,"MetadataSource":1}, "Label":{"__type":"Label:http:\/\/services.kexp.org\/","Uri":"http:\/\/services.kexp.org\/rest\/labels\/37438","MusicBrainzId":null,"Name":"KEXP","Country":null,"ReleaseEvents":null,"MetadataSource":1}, "ReleaseEvent":{"__type":"ReleaseEvent:http:\/\/services.kexp.org\/","Uri":"http:\/\/services.kexp.org\/rest\/releaseevents\/238950","BarCode":null,"CatalogNumber":null,"Country":null, "Date":{"Year":2011,"Month":null,"Day":null}, "Label":{"Uri":"http:\/\/services.kexp.org\/rest\/labels\/37438"}, "Release":{"Uri":"http:\/\/services.kexp.org\/rest\/releases\/186797"}, "ReleaseFormat":1}, "Comments":[{"__type":"PlayComment:http:\/\/services.kexp.org\/","Uri":"http:\/\/services.kexp.org\/rest\/comments\/533446","Text":"http:\/\/keepshellyinathens.blogspot.com\/","IsDeleted":false,"CreatedDate":"\/Date(1321033618207)\/","UpdatedDate":"\/Date(1321033618207)\/", "User":{"__type":"User:http:\/\/services.kexp.org\/","Uri":"http:\/\/services.kexp.org\/rest\/users\/22","UserKey":null,"DisplayName":"John Richards","Comments":null,"Opinions":null}, "Play":null}], "Opinions":null}] }

Programs

Returns the programs for the specified channel. If no channel is included in the request, the programs for all channels are returned.

Parameters

Name Value Required Default
channel 1 or 2 (1 = Seattle, 2 = New York) No Data for all channels returned

Sample response

{ "Count":4,"ResponseDate":"\/Date(1321036398750)\/","PersistenceDate":"\/Date(1321033233000)\/", "Programs":[{"Uri":"http:\/\/services.kexp.org\/rest\/programs\/50","Name":"Mo'Glo","Tags":"World", "Channel":{"__type":"Channel:http:\/\/services.kexp.org\/","Uri":"http:\/\/services.kexp.org\/rest\/channels\/2","Name":"KEXP 91.5 FM New York","StreamUri":"http:\/\/www.digitalwell.washington.edu\/dw\/1\/51\/7c\/7c012464-a186-4019-96be-88fa276604be.wma","IsActive":false,"Programs":null,"TimeZone":"Eastern Standard Time","TimeZoneOffset":-5}, "Shows":null}, {"Uri":"http:\/\/services.kexp.org\/rest\/programs\/49","Name":"To The 5 Boroughs","Tags":"Rock,Eclectic", "Channel":{"__type":"Channel:http:\/\/services.kexp.org\/","Uri":"http:\/\/services.kexp.org\/rest\/channels\/2","Name":"KEXP 91.5 FM New York","StreamUri":"http:\/\/www.digitalwell.washington.edu\/dw\/1\/51\/7c\/7c012464-a186-4019-96be-88fa276604be.wma","IsActive":false,"Programs":null,"TimeZone":"Eastern Standard Time","TimeZoneOffset":-5}, "Shows":null}, {"Uri":"http:\/\/services.kexp.org\/rest\/programs\/51","Name":"Variety Mix","Tags":"Rock,Eclectic", "Channel":{"__type":"Channel:http:\/\/services.kexp.org\/","Uri":"http:\/\/services.kexp.org\/rest\/channels\/2","Name":"KEXP 91.5 FM New York","StreamUri":"http:\/\/www.digitalwell.washington.edu\/dw\/1\/51\/7c\/7c012464-a186-4019-96be-88fa276604be.wma","IsActive":false,"Programs":null,"TimeZone":"Eastern Standard Time","TimeZoneOffset":-5}, "Shows":null}, {"Uri":"http:\/\/services.kexp.org\/rest\/programs\/48","Name":"Wake Up","Tags":"Rock,Eclectic", "Channel":{"__type":"Channel:http:\/\/services.kexp.org\/","Uri":"http:\/\/services.kexp.org\/rest\/channels\/2","Name":"KEXP 91.5 FM New York","StreamUri":"http:\/\/www.digitalwell.washington.edu\/dw\/1\/51\/7c\/7c012464-a186-4019-96be-88fa276604be.wma","IsActive":false,"Programs":null,"TimeZone":"Eastern Standard Time","TimeZoneOffset":-5}, "Shows":null}] }

Returns the programs having a matching tag for the specified channel. If no channel is included in the request, the programs for all channels are returned.

Parameters

Name Value Required Default
tag Tag name Yes
channel 1 or 2 (1 = Seattle, 2 = New York) No Data for all channels returned

Note: Tag nams are not case-sensitive. All of the tag names can be retrieved with /cache/getProgramTags.

Sample response

{ "Count":3,"ResponseDate":"\/Date(1321036751067)\/","PersistenceDate":"\/Date(1321033233000)\/", "Programs":[{"Uri":"http:\/\/services.kexp.org\/rest\/programs\/49","Name":"To The 5 Boroughs","Tags":"Rock,Eclectic", "Channel":{"__type":"Channel:http:\/\/services.kexp.org\/","Uri":"http:\/\/services.kexp.org\/rest\/channels\/2","Name":"KEXP 91.5 FM New York","StreamUri":"http:\/\/www.digitalwell.washington.edu\/dw\/1\/51\/7c\/7c012464-a186-4019-96be-88fa276604be.wma","IsActive":false,"Programs":null,"TimeZone":"Eastern Standard Time","TimeZoneOffset":-5}, "Shows":null}, {"Uri":"http:\/\/services.kexp.org\/rest\/programs\/51","Name":"Variety Mix","Tags":"Rock,Eclectic", "Channel":{"__type":"Channel:http:\/\/services.kexp.org\/","Uri":"http:\/\/services.kexp.org\/rest\/channels\/2","Name":"KEXP 91.5 FM New York","StreamUri":"http:\/\/www.digitalwell.washington.edu\/dw\/1\/51\/7c\/7c012464-a186-4019-96be-88fa276604be.wma","IsActive":false,"Programs":null,"TimeZone":"Eastern Standard Time","TimeZoneOffset":-5}, "Shows":null}, {"Uri":"http:\/\/services.kexp.org\/rest\/programs\/48","Name":"Wake Up","Tags":"Rock,Eclectic", "Channel":{"__type":"Channel:http:\/\/services.kexp.org\/","Uri":"http:\/\/services.kexp.org\/rest\/channels\/2","Name":"KEXP 91.5 FM New York","StreamUri":"http:\/\/www.digitalwell.washington.edu\/dw\/1\/51\/7c\/7c012464-a186-4019-96be-88fa276604be.wma","IsActive":false,"Programs":null,"TimeZone":"Eastern Standard Time","TimeZoneOffset":-5}, "Shows":null}] }

Returns all of the tag names that have been applied to programs.

Parameters

Name Value Required Default
(none)

Sample response

{ "Count":4,"ResponseDate":"\/Date(1321037011750)\/","PersistenceDate":"\/Date(1321033233000)\/", "Tags":[{"Name":"African","UsageCount":1}, {"Name":"Blues","UsageCount":4}, {"Name":"Country","UsageCount":4}, {"Name":"Eclectic","UsageCount":6}] }

Shows

Returns the most recent shows (last 14 days) grouped as specified for the specified channel. If no channel is included in the request, the recent shows for all channels are returned.

Parameters

Name Value Required Default
groupBy One of the literals: date, host, program, or tag Yes
channel 1 or 2 (1 = Seattle, 2 = New York) No Data for all channels returned

Note: The Count property of the response reflects the number of groupings (i.e. dates, hosts, programs, or tags) in the returned data, not the number of shows returned. Each show may appear in multiple groupings. For example, if grouping by host, a show with two hosts would show up under each of the two hosts.

Sample response

{ "Count":2,"ShowDate":"\/Date(1320796800000)\/","ResponseDate":"\/Date(1322089406213)\/","PersistenceDate":"\/Date(1322089394000)\/", "Items":[{"Host":{"Uri":"http:\/\/services.kexp.org\/rest\/hosts\/296","Name":"Abe Beeson","ImageUri":"https:\/\/kexpstorage.blob.core.windows.net\/images\/hosts\/111328","User":null,"IsActive":true,"ShowHosts":null}, "Shows":[{"Uri":"http:\/\/services.kexp.org\/rest\/shows\/53129","AirDate":"\/Date(1320829200000)\/","Tagline":"Subbin' for Tim","IsDeleted":false,"CreatedDate":"\/Date(1320829126997)\/","UpdatedDate":"\/Date(1320829126997)\/", "Program":{"__type":"Program:http:\/\/services.kexp.org\/","Uri":"http:\/\/services.kexp.org\/rest\/programs\/1","Name":"Variety Mix","Tags":"Rock,Eclectic","Description":"KEXP Radio hand selects all of its music, with expert DJs showcasing both established and emerging bands. Rock is generally a broad term for KEXP, as indie and alternative sounds are often blended with a variety of other genres in an innovative music format. KEXP variety mix programming makes up the bulk of our broadcast service, bringing listeners an edgy mix of alternative rock, hip hop, electronic, roots & blues, world, jazz and more.", "Channel":{"Uri":"http:\/\/services.kexp.org\/rest\/channels\/1"}, "Shows":null}, "ShowHosts":[{"__type":"ShowHost:http:\/\/services.kexp.org\/","Uri":"http:\/\/services.kexp.org\/rest\/showhosts\/27679", "Show":{"Uri":"http:\/\/services.kexp.org\/rest\/shows\/53129"}, "Host":{"__type":"Host:http:\/\/services.kexp.org\/","Uri":"http:\/\/services.kexp.org\/rest\/hosts\/296","Name":"Abe Beeson","ImageUri":"https:\/\/kexpstorage.blob.core.windows.net\/images\/hosts\/111328","User":null,"IsActive":true,"ShowHosts":null}}]}]}, {"Host":{"Uri":"http:\/\/services.kexp.org\/rest\/hosts\/313","Name":"Brian Foss","ImageUri":"https:\/\/kexpstorage.blob.core.windows.net\/images\/hosts\/111329","User":null,"IsActive":true,"ShowHosts":null}, "Shows":[{"Uri":"http:\/\/services.kexp.org\/rest\/shows\/53200","AirDate":"\/Date(1321765200000)\/","Tagline":"","IsDeleted":false,"CreatedDate":"\/Date(1321765304800)\/","UpdatedDate":"\/Date(1321765304800)\/", "Program":{"__type":"Program:http:\/\/services.kexp.org\/","Uri":"http:\/\/services.kexp.org\/rest\/programs\/46","Name":"Sonic Reducer","Tags":"Punk,Rock","Description":"Sonic Reducer brings you three hours of the best in local, national, international punk and hardcore. Your hosts, Brian, Nick and Mr. West drag you through a mess of short, fast and loud songs from today and back in the day every Saturday night from 9pm to midnight.", "Channel":{"Uri":"http:\/\/services.kexp.org\/rest\/channels\/1"}, "Shows":null}, "ShowHosts":[{"__type":"ShowHost:http:\/\/services.kexp.org\/","Uri":"http:\/\/services.kexp.org\/rest\/showhosts\/27750", "Show":{"Uri":"http:\/\/services.kexp.org\/rest\/shows\/53200"}, "Host":{"__type":"Host:http:\/\/services.kexp.org\/","Uri":"http:\/\/services.kexp.org\/rest\/hosts\/313","Name":"Brian Foss","ImageUri":"https:\/\/kexpstorage.blob.core.windows.net\/images\/hosts\/111329","User":null,"IsActive":true,"ShowHosts":null}}]}]}] }

Returns the show having a matching Id.

Parameters

Name Value Required Default
showId Show Id value Yes

Note: The show Id can be obtained from the show Uri that is associated with a play.

Sample response

{ "Count":1,"ShowDate":"\/Date(1320282000000)\/","ResponseDate":"\/Date(1321037402189)\/","PersistenceDate":"\/Date(1320979313000)\/", "Shows":[{"Uri":"http:\/\/services.kexp.org\/rest\/shows\/53100","AirDate":"\/Date(1320282000000)\/","Tagline":"covering a bit for Greg Vandy","IsDeleted":false,"CreatedDate":"\/Date(1320282208137)\/","UpdatedDate":"\/Date(1320282208137)\/", "Program":{"__type":"Program:http:\/\/services.kexp.org\/","Uri":"http:\/\/services.kexp.org\/rest\/programs\/4","Name":"Roadhouse","Tags":"Blues,Country,Roots", "Channel":{"Uri":"http:\/\/services.kexp.org\/rest\/channels\/1"}, "Shows":null}, "ShowHosts":[{"__type":"ShowHost:http:\/\/services.kexp.org\/","Uri":"http:\/\/services.kexp.org\/rest\/showhosts\/27650", "Show":{"Uri":"http:\/\/services.kexp.org\/rest\/shows\/53100"}, "Host":{"__type":"Host:http:\/\/services.kexp.org\/","Uri":"http:\/\/services.kexp.org\/rest\/hosts\/300","Name":"Kevin Cole","ImageUri":"https:\/\/kexpstorage.blob.core.windows.net\/images\/hosts\/111356","User":null,"IsActive":true,"ShowHosts":null}}]}] }

Returns the shows that aired between the start and end date/times, inclusive, for the specified channel. If no start time is specified, the current time is assumed. If no end time is specified, the start time is used as the end time (so omitting both returns the currently airing show). If no channel is included in the request, the shows for all channels are returned.

Parameters

Name Value Required Default
startTime Earliest airdate to retrieve No Current date/time
endTime Lateest airdate to retrieve No startTime (current date/time if both omitted)
channel 1 or 2 (1 = Seattle, 2 = New York) No Data for all channels returned

Sample response

{ "Count":2,"ShowDate":"\/Date(1321032600000)\/","ResponseDate":"\/Date(1321037703072)\/","PersistenceDate":"\/Date(1321037296000)\/", "Shows":[{"Uri":"http:\/\/services.kexp.org\/rest\/shows\/53142","AirDate":"\/Date(1321020000000)\/","Tagline":"The Morning Show","IsDeleted":false,"CreatedDate":"\/Date(1321020073750)\/","UpdatedDate":"\/Date(1321020073750)\/", "Program":{"__type":"Program:http:\/\/services.kexp.org\/","Uri":"http:\/\/services.kexp.org\/rest\/programs\/1","Name":"Variety Mix","Tags":"Rock,Eclectic", "Channel":{"Uri":"http:\/\/services.kexp.org\/rest\/channels\/1"},"Shows":null}, "ShowHosts":[{"__type":"ShowHost:http:\/\/services.kexp.org\/","Uri":"http:\/\/services.kexp.org\/rest\/showhosts\/27692", "Show":{"Uri":"http:\/\/services.kexp.org\/rest\/shows\/53142"}, "Host":{"__type":"Host:http:\/\/services.kexp.org\/","Uri":"http:\/\/services.kexp.org\/rest\/hosts\/279","Name":"John Richards","ImageUri":"https:\/\/kexpstorage.blob.core.windows.net\/images\/hosts\/111353","User":null,"IsActive":true,"ShowHosts":null}}]}, {"Uri":"http:\/\/services.kexp.org\/rest\/shows\/53143","AirDate":"\/Date(1321034400000)\/","Tagline":"The Midday Show","IsDeleted":false,"CreatedDate":"\/Date(1321034319037)\/","UpdatedDate":"\/Date(1321034319037)\/", "Program":{"__type":"Program:http:\/\/services.kexp.org\/","Uri":"http:\/\/services.kexp.org\/rest\/programs\/1","Name":"Variety Mix","Tags":"Rock,Eclectic", "Channel":{"Uri":"http:\/\/services.kexp.org\/rest\/channels\/1"},"Shows":null}, "ShowHosts":[{"__type":"ShowHost:http:\/\/services.kexp.org\/","Uri":"http:\/\/services.kexp.org\/rest\/showhosts\/27693", "Show":{"Uri":"http:\/\/services.kexp.org\/rest\/shows\/53143"}, "Host":{"__type":"Host:http:\/\/services.kexp.org\/","Uri":"http:\/\/services.kexp.org\/rest\/hosts\/283","Name":"Cheryl Waters","ImageUri":"https:\/\/kexpstorage.blob.core.windows.net\/images\/hosts\/111330","User":null,"IsActive":true,"ShowHosts":null}}]}] }

Cache Statistics

Returns statistics about the operation of the programming cache.

Parameters

Name Value Required Default
(none)

Return Values

Name Value Expectation
EarliestPlay UTC date of earliest play cached 1/1/2000 (once cache is fully loaded)
EarliestShow UTC date of earliest show cached 1/1/2000 (once cache is fully loaded)
LatestPlay UTC date of latest play cached Today's date (UTC)
LatestRecentPlaysUpdate Last UTC date/time that recent plays were updated Within 5 seconds of current time
LatestShow UTC date of latest show cached Today's date (UTC)
OutputCacheHitRatio Latest performance counter value for ASP.NET output cache hit/miss ratio Higher is better: 85+
OutputCacheHits Latest performance counter value for ASP.NET output cache total hits Higher is better: Depends on usage and total cache uptime
OutputCacheMisses Latest performance counter value for ASP.NET output cache total misses Lower is better: Depends on usage and total cache uptime
OutputCacheTurnoverRate Latest performance counter value for ASP.NET output cache turnover (average number of cache additions/removals per second) Lower is better: Depends on usage and cache profile values in web.config

Sample response

{ "EarliestPlay":"\/Date(946684800000)\/","EarliestShow":"\/Date(946684800000)\/", "LatestPlay":"\/Date(1320969600000)\/","LatestRecentPlaysUpdate":"\/Date(1321037894000)\/","LatestShow":"\/Date(1320969600000)\/", "OutputCacheHitRatio":44.2385635,"OutputCacheHits":764,"OutputCacheMisses":963,"OutputCacheTurnoverRate":0.4662061, "TotalDaysPlays":4333,"TotalDaysShows":4333 }