Using the API

JonTheNiceGuy edited this page Jan 14, 2013 · 1 revision

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.

Table of Contents

Using the API

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.

JSON Requests

echo

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"}}

echologin

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.

listartists

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\/"}}

searchartists

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[]

listtracks

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\/"}}

searchtracks

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[]

gettrack

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).

getartist

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).

newtrack

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"}

getshowid

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"}

addtracktoshow

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"}

getchartdata

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.

HTTP response only functions

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.

vote

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).

newtrackbumper

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.

newshowbumper

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.

makechart

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.

shell/finalizedaily|weekly|monthly/yyyymmdd (can also be spelt finalise)

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.

editshow

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.

BASH variable settings

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"

shell/getnewdailytrack

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

shell/getnewweeklytrack

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

shell/getoldweeklytrack

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

shell/getnewmonthlytrack

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

shell/artist

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"

shell/artistsounds

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"

shell/title

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"

shell/titlesounds

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"

shell/license

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"

shell/isnsfw

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

shell/trackprebumper

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"

shell/trackpostbumper

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"

shell/showprebumper

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"

shell/showmidbumper

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"

shell/showpostbumper

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"

shell/file

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"

shell/votes

Return a non-adjusted number of votes for a track.

  curl http://example.com/api/shell/votes/1

Responds with:

  VOTES=1

shell/shows

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

shell/votesadj

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

shell/showiddaily

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

shell/showurldaily

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

shell/shownamedaily

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"

shell/showidweekly

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

shell/showurlweekly

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

shell/shownameweekly

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"

shell/showidmonthly

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

shell/showurlmonthly

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

shell/shownamemonthly

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"

newtrack

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

getunplayedtracks

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
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.