Using the API
Please note that this document has not been updated since the move to CCHits.net's rewrite, and as such, some details may be inaccurate. That said, this is still relatively up-to-date.
The API is split into three parts, one part generates JSON responses to use in your own web pages, another replies with simple HTTP status codes, while the last is used by the various shell scripts to set variables for generating the daily, weekly and monthly tracks.
Return the data handled by the API, either by an authenticated user, or not. For example:
curl http://user:password@example.com/api/echo/SomeTestData?test=abc123
This will return
json{"Auth":{"user":"user","pass":"p******d"},"ReqPath":["echo","SomeTestData"],"Data":{"test":"abc123"}}
Similarly, without authentication
curl http://example.com/api/echo/SomeTestData?test=abc123
This will return
json{"Auth":{"user":"","pass":""},"ReqPath":["echo","SomeTestData"],"Data":{"test":"abc123"}}
Return the data handled by the API, requiring a login using basic authentication. For example:
curl http://user:password@example.com/api/echo/SomeTestData?test=abc123
This will return
json{"Auth":{"user":"user","pass":"p******d"},"ReqPath":["echo","SomeTestData"],"Data":{"test":"abc123"}}
Trying to perform this request without providing basic authentication will return a 401 ("Unauthorized") error message.
Return a number (default: 25) of artists in ascending alphabetical order. Optionally specify the number of results you want and what multiple of that number to start at. For example:
curl http://example.com/api/listartists/size1/page1
This will return
json{"1":{"intArtistID":"1","strArtistName":"A Test Artist","strArtistNameSounds":"Ay Test Arteest","strArtistUrl":"http:\/\/example.com\/"}}
Return a number (default: 25) of artists in ascending alphabetical order which begin with the letters specified. For example:
curl http://example.com/api/searchartists/a
This will return
json{"1":{"intArtistID":"1","strArtistName":"A Test Artist","strArtistNameSounds":"Ay Test Arteest","strArtistUrl":"http:\/\/example.com\/"}}
Optionally specify the number of results you want and what multiple of that number to start at. For example:
curl http://example.com/api/searchartists/a/size1/page1
If the search returns no data, it will return:
json[]
Return a number (default: 25) of tracks in ascending alphabetical order. Optionally specify the number of results you want and what multiple of that number to start at. For example:
curl http://example.com/api/listtracks/size1/page1
This will return
json{"1":{"intTrackID":"1","intArtistID":"1","strTrackName":"A Test Track","strTrackNameSounds":"Ay Test Trak","strTrackUrl":"http:\/\/example.com\/track","enumTrackLicense":"cc-by","isNSFW":"0","datDailyShow":"","strArtistName":"A Test Artist","strArtistNameSounds":"Ay Test Arteest","strArtistUrl":"http:\/\/example.com\/"}}
Return a number (default: 25) of tracks in ascending alphabetical order which begin with the letters specified. For example:
curl http://example.com/api/searchtracks/a
This will return
json{"1":{"intTrackID":"1","intArtistID":"1","strTrackName":"A Test Track","strTrackNameSounds":"Ay Test Trak","strTrackUrl":"http:\/\/example.com\/track","enumTrackLicense":"cc-by","isNSFW":"0","datDailyShow":"","strArtistName":"A Test Artist","strArtistNameSounds":"Ay Test Arteest","strArtistUrl":"http:\/\/example.com\/"}}
Optionally specify the number of results you want and what multiple of that number to start at. For example:
curl http://example.com/api/searchtracks/a/size1/page1
If the search returns no data, it will return:
json[]
Return details about a specific track. For example:
curl http://example.com/api/gettrack/1
This will return
json{"trackid":1,"artist":{"name":"A Test Artist","sounds":"Ay Test Arteest","url":"http:\/\/example.com\/"},"track":{"name":"A Test Track","sounds":"Ay Test Trak","url":"http:\/\/example.com\/track"},"license":"cc-by","licensetext":"By Attribution","isnsfw":"0","since":"2000-12-31 23:59:59","chart":"1","chart_yest":"2","votes":"1","showcount":1,"votesadj":0.95,"showadj":1,"I_Voted":"N\/A","shows":[{"url":"http:\/\/example.com\/monthly\/200012","name":"Example.Com Monthly Top Tracks Show for 2000-12"}]}
If you pass this request with no track number, or an invalid identifier, it will return a HTTP Status of 400 (Bad Request).
Return details about a specific artist and the tracks they have in the system. For example:
curl http://example.com/api/getartist/1
This will return
json{"strArtistName":"A Test Artist","strArtistNameSounds":"Ay Test Arteest","strArtistUrl":"http:\/\/example.com","arrTracks":[{"intTrackID":"1"}]}
If you pass this request with no artist identifier, or an invalid identifier, it will return a HTTP Status of 400 (Bad Request).
Upload a file and return that track's reference. Optionally add it directly to an external show. For example:
curl http://user:password@example.com/api/newtrack -F "strTrackName=A Test Track" -F "strTrackNameSounds=Ay Test Trak" -F "strTrackUrl=http://example.com/track" -F "enumTrackLicense=cc-by" -F "isNSFW=0" -F "strArtistName=A Test Artist" -F "strArtistNameSounds=Ay Test Arteest" -F "strArtistUrl=http://example.com" -F "files=@MyUploadFile.mp3"
You can also supply the artist ID if you have that already. Note this is not the preferred method for individual tracks. Here is an example API call, providing the Artist ID instead of the artist's details:
curl http://user:password@example.com/api/newtrack -F "strTrackName=A Test Track" -F "strTrackNameSounds=Ay Test Trak" -F "strTrackUrl=http://example.com/track" -F "enumTrackLicense=cc-by" -F "isNSFW=0" -F "intArtistID=1" -F "files=@MyUploadFile.mp3"
If you refer to an ArtistID which doesn't exist, it will return a status code of 404 (Not found). For this reason, it is recommended that you provide the Artist details by default, unless you are uploading a lot of tracks by one artist. If your request doesn't contain all the fields described in one of the two examples, then the site will return a status code of 405 (Method not allowed). If you provide authentication details which do not have uploading privilidges, then the site will return a status code of 403 (Forbidden). If you managed to get all the fields entered, then the system will return with the track identifier.
json{"intTrackID":"1"}
Given a URL and show name, return a show ID for the purposes of providing a link to the show when providing voting links or to add tracks to a show.
curl http://user:password@example.com/api/getshowid -F "strShowUrl=http://www.example.com/path/to/show/notes" -F "strShowName=An Example Show"
This will return
json{"intShowID":"1"}
This is only for the use of podcasters who are playing a track they know is listed on the site. Provide the API call with either a Show URL and Show Name or a Show ID, a track number and optionally the place the track is in the show (as a track number within the show, not a timestamp!) to create a listing to your track.
curl http://user:password@example.com/api/addtracktoshow -F "strShowUrl=http://www.example.com/path/to/show/notes" -F "strShowName=An Example Show" -F "intTrackID=1" -F "intPartID=1"
Or
curl http://user:password@example.com/api/addtracktoshow -F "intShowID=1" -F "intTrackID=1" -F "intPartID=1"
This will return
json{"intShowID":"1"}
This will return full chart data for a track.
curl http://example.com/api/getchartdata/1
This will return
json{"positions":[{"datChart":"2000-12-29","intPositionID":"1"},{"datChart":"2000-12-30","intPositionID":"2"}],"highest":[{"datChart":"2000-12-29","intPositionID":"1"}]}
If you provide a track number not known by the site, it will return an HTTP error 404.
These functions will only return an HTTP code (like 200 OK, 404 Not Found or similar). As such, the API calls will only list what codes you should test for.
Show you have liked this particular track, and optionally, identify which show number you have listened to it on. For example:
curl http://example.com/api/vote/1
The above votes for track 1, without specifying the show. You could refer to show number 100 by requesting the following URL
curl http://example.com/api/vote/1/100
This will return an HTTP Status of 200 if a vote for this track has not already been cast, or 400 (Bad Request) if a vote has been cast already. If the track doesn't exist, it will return an error code 404 (Not Found).
Upload a track bumper. This call requires the track ID that the bumper relates to, the position of the bumper (pre or post), and what type of bumper it is (tts, presenter, artist, fan). Note, the position (enumPosition) and the type of bumper (enumType) need to be supplied in lower case. For example:
curl http://user:password@example.com/api/newtrackbumper -F "intTrackID=1" -F "enumType=tts" -F "enumPosition=pre" -F "files=@MyUploadFile.mp3"
This will return an HTTP Status of 204 (No content to follow) if the action succeeded, but if there is a problem it will return 403 (Forbidden) if the user is not permitted to upload bumpers, 500 (Internal Server Error) if the system was unable to insert it into the available bumpers, or 405 (Method not allowed) if the required data fields are not all supplied.
Upload a show bumper. This call requires the show ID that the bumper relates to, the position of the bumper (pre or post). Note, the position (enumPosition) needs to be supplied in lower case. For example:
curl http://user:password@example.com/api/newshowbumper -F "intShowID=1" -F "enumPosition=pre" -F "files=@MyUploadFile.mp3"
This will return an HTTP Status of 204 (No content to follow) if the action succeeded, but if there is a problem it will return 403 (Forbidden) if the user is not permitted to upload bumpers, 500 (Internal Server Error) if the system was unable to insert it into the available bumpers, or 405 (Method not allowed) if the required data fields are not all supplied.
Perform an analysis of the current chart position and update or insert this data in to the appropriate tables. For example:
curl http://user:password@example.com/api/makechart
This will return an HTTP status code of 403 (Forbidden) if the user is not permitted to request this function, or 200 once the function has been performed. This call is reserved for CRONTAB style requests, and should never be performed by normal users.
Provide the show entry with details about the running time of a track, or a hash for the track:
curl http://user:password@example.com/api/shell/finalize/daily/20001231 -F "time=00:00:00" -F "hash=0123456789abcdef0123456789abcdef0123456789"
This function is used once a show track has been generated by the site and is used to populate the RSS feeds with running times and a cryptographic hash of the track to populate the GUID.
Amend a show entry that you have submitted.
curl http://user:password@ example .com/api/editshow -F intShowID=1 -F "strShowName=A show name" -F "strShowUrl=http:// example .org/showname/episode"
This will return an HTTP status code of 200 if the change was successful or 500 if any error occurred while making the change - including if you are not permitted to make that change because you were not the creator of that show.
All of these functions are designed to be used in a simple shell script. The shell script will run eval `http://example.com/api/shell/FUNCTION` in order to get appropriate data. The functions SHOULD return data as follows: VARIABLE="DATA"
Request a single track to create the daily show with. For example:
curl http://user:password@example.com/api/shell/getnewdailytrack
Responds with:
TRACK=1
The weekly show plays the last 7 days of daily tracks, and then a number of tracks from the week before (based on the number of votes each of those tracks has received) to create the weekly show. This API call requests a single track from the last 7 days of daily tracks. For example:
curl http://user:password@example.com/api/shell/getnewweeklytrack/1
Responds with:
TRACK=1
Like the getnewweeklytrack, this API call requests a single track from the week before this show is generated, ordered by the highest number of votes. For example:
curl http://user:password@example.com/api/shell/getoldweeklytrack/1
Responds with:
TRACK=50
This API call behaves in a similar way to the getoldweeklytrack call, in that it returns tracks, ordered by the highest votes. In this case, rather than selecting this track from the last X number of days, it returns the tracks from the whole database of tracks. For example:
curl http://user:password@example.com/api/shell/getnewmonthlytrack/1
Responds with:
TRACK=1
Returns the artist name for the supplied track number. For example:
curl http://example.com/api/shell/artist/1
Responds with:
ARTIST="A Test Artist"
Returns the festival version of the artists name for the referenced track number in order to generate the TTS version of the track bumper. For example:
curl http://example.com/api/shell/artistsounds/1
Responds with:
ARTISTSOUNDS="Ay Test Arteest"
Returns the track title for the supplied track number. For example:
curl http://example.com/api/shell/title/1
Responds with:
TITLE="A Test Track"
Returns the festival version of the track title for the referenced track number in order to generate the TTS version of the track bumper. For example:
curl http://example.com/api/shell/titlesounds/1
Responds with:
TITLESOUNDS="Ay Test Trak"
Returns the license the track (identified by the track number) has been released under. For example:
curl http://example.com/api/shell/license/1
Responds with:
LICENSE="cc-by"
Returns whether the track is considered to be family or workplace friendly as a TRUE or FALSE value. For example:
curl http://example.com/api/shell/isnsfw/1
Responds with:
NSFW=FALSE
Get the file name of a randomized bumper to play before a track. Note, this call does not return system paths, as this work may be being performed off-box, using SFTP, HTTP, and thus the "base path" would be configured in the environment variables for the script. For example:
curl http://example.com/api/shell/trackprebumper/1
Responds with:
TRACKPREBUMPER="1.1.source"
Get the file name of a randomized bumper to play after the track. Like all the bumper requests, this call does not return system paths, as this work may be being performed off-box, using SFTP, HTTP, and thus the "base path" would be configured in the environment variables for the script. For example:
curl http://example.com/api/shell/trackpostbumper/1
Responds with:
TRACKPOSTBUMPER="1.2.source"
Get the file name of a randomized bumper to play at the beginning of a show, after the introduction tune. Note, this call does not return system paths, as this work may be being performed off-box, using SFTP, HTTP, and thus the "base path" would be configured in the environment variables for the script. For example:
curl http://example.com/api/shell/showprebumper/daily/20001231
Responds with:
SHOWPREBUMPER="1.1.source"
Get the file name of a randomized bumper to play in between tracks during a show, only for use in weekly and monthly shows. Note, this call does not return system paths, as this work may be being performed off-box, using SFTP, HTTP, and thus the "base path" would be configured in the environment variables for the script. For example:
curl http://example.com/api/shell/showmidbumper/weekly/20001231
Responds with:
SHOWMIDBUMPER="1.1.source"
Get the file name of a randomized bumper to play at the end of a show, before the exit tune. Note, this call does not return system paths, as this work may be being performed off-box, using SFTP, HTTP, and thus the "base path" would be configured in the environment variables for the script. For example:
curl http://example.com/api/shell/showpostbumper/daily/20001231
Responds with:
SHOWPOSTBUMPER="1.1.source"
Get the file name of the track to be played in a show. Note, this call does not return system paths, as this work may be being performed off-box, using SFTP, HTTP, and thus the "base path" would be configured in the environment variables for the script. For example:
curl http://example.com/api/shell/file/1
Responds with:
FILE="1.source"
Return a non-adjusted number of votes for a track.
curl http://example.com/api/shell/votes/1
Responds with:
VOTES=1
Return the number of shows a track has been played in. Note this number will include all shows, not just weekly and monthly shows that will affect the vote adjustment.
curl http://example.com/api/shell/shows/1
Responds with:
SHOWS=1
Return an adjusted number of votes for a track. For details on vote adjustment, please see the vote adjustment page.
curl http://example.com/api/shell/votesadj/1
Responds with:
VOTESADJ=1
Return the internal ID number of the show. Optionally, provide a date stamp to return the show ID number for.
curl http://example.com/api/shell/showiddaily/20001231
Responds with:
SHOWID=1
Return the final part of the show URL for the show. Optionally, provide a date stamp to return the show URL for. It may seem a little odd having a function which returns the same code as the code which is supplied, however, this is used extensively in the show generation code, as that doesn't provide a datestamp, and the system will return an appropriate datestamp.
curl http://example.com/api/shell/showurldaily/20001231
Responds with:
SHOWID=20001231
Return the ID3 tag to be used in the show name. Optionally, provide a date stamp to return the show ID3 tag for.
curl http://example.com/api/shell/shownamedaily/20001231
Responds with:
SHOWID="The Daily Exposure Show for 2000-12-31"
Return the internal ID number of the show. Optionally, provide a date stamp to return the show ID number for.
curl http://example.com/api/shell/showidweekly/20001231
Responds with:
SHOWID=1
Return the final part of the show URL for the show. Optionally, provide a date stamp to return the show URL for. It may seem a little odd having a function which returns the same code as the code which is supplied, however, this is used extensively in the show generation code, as that doesn't provide a datestamp, and the system will return an appropriate datestamp.
curl http://example.com/api/shell/showurlweekly/20001231
Responds with:
SHOWID=20001231
Return the ID3 tag to be used in the show name. Optionally, provide a date stamp to return the show ID3 tag for.
curl http://example.com/api/shell/shownameweekly/20001231
Responds with:
SHOWID="The Weekly Review Show for the week ending 2000-12-31"
Return the internal ID number of the show. Optionally, provide a date stamp to return the show ID number for.
curl http://example.com/api/shell/showidmonthly/200012
Responds with:
SHOWID=1
Return the final part of the show URL for the show. Optionally, provide a date stamp to return the show URL for. It may seem a little odd having a function which returns the same code as the code which is supplied, however, this is used extensively in the show generation code, as that doesn't provide a datestamp, and the system will return an appropriate datestamp.
curl http://example.com/api/shell/showurlmonthly/200012
Responds with:
SHOWID=200012
Return the ID3 tag to be used in the show name. Optionally, provide a date stamp to return the show ID3 tag for.
curl http://example.com/api/shell/shownamemonthly/200012
Responds with:
SHOWID="The Monthly Chart Show for the month 2000-12"
This is the same as the JSON call, but returns a shell variable instead of a JSON value.
Upload a file and return that track's reference. Optionally add it directly to an external show. For example:
curl http://user:password@example.com/api/shell/newtrack -F "strTrackName=A Test Track" -F "strTrackNameSounds=Ay Test Trak" -F "strTrackUrl=http://example.com/track" -F "enumTrackLicense=cc-by" -F "isNSFW=0" -F "strArtistName=A Test Artist" -F "strArtistNameSounds=Ay Test Arteest" -F "strArtistUrl=http://example.com" -F "files=@MyUploadFile.mp3"
You can also supply the artist ID if you have that already. Note this is not the preferred method for individual tracks. Here is an example API call, providing the Artist ID instead of the artist's details:
curl http://user:password@example.com/api/shell/newtrack -F "strTrackName=A Test Track" -F "strTrackNameSounds=Ay Test Trak" -F "strTrackUrl=http://example.com/track" -F "enumTrackLicense=cc-by" -F "isNSFW=0" -F "intArtistID=1" -F "files=@MyUploadFile.mp3"
If you refer to an ArtistID which doesn't exist, it will return a status code of 404 (Not found). For this reason, it is recommended that you provide the Artist details by default, unless you are uploading a lot of tracks by one artist. If your request doesn't contain all the fields described in one of the two examples, then the site will return a status code of 405 (Method not allowed). If you provide authentication details which do not have uploading privilidges, then the site will return a status code of 403 (Forbidden). If you managed to get all the fields entered, then the system will return with the track identifier.
TRACKID=1
This call returns the number of tracks which have not been played on a daily show, and is used internally to gauge how long it will be until an administrator needs to find new tracks to upload! For example:
curl http://example.com/api/getunplayedtracks
This returns:
UNPLAYED_TRACKS=2