Documentation

Welcome to the documentation for the Top40 API. This is an assignment for Web Technology (2ID60) at the Eindhoven University of Technology 2014/2015 .

Table of Contents

Authentication

In order to authenticate all requests must contain the following key=%KEY% in the query. When you fail to authenticate you will recieve the following response: 

{
    "error":"Please provide authentication"
}
Response when no key is provided 
{
    "error":"An incorrect key was provided"
}
Response when an incorrect key is provided


*** Please use the following key to test the functionality of the api: HXMJ9V8x2qfZb0LkBnoPBHPTpfxzUQ0p***

Calling the API

The API is called by appending the home-url with php/database.php?%request% where %request% is your specific API request. In our installation of the site home-url is http://www.jochemkuijpers.nl/tue/2ID60/top40/. Thus to call the API I would call http://www.jochemkuijpers.nl/tue/2ID60/top40/php/database.php?%request%.

Get

A GET request returns the information associated with the requested object. These objects can be either information a specific song, a search query, the top40 list or a 'prep' request.

Should an error have occured the following response will be shown: 

{
    "error":"An error has occured"
}
The default error message

Song

This request gathers all the information known about a song in our database. It requires the SongID and WeekID of the requested song. To make this call the following request is done: GET <home-url>php/database.php?query=song&songID=%SONGID%&weekID=%WEEKID%&key=%KEY%. A response would be as follows: 

{
    "Title":"Thinking out loud",
    "Artist":"Ed Sheeran",
    "VideoID":"lp-EO5I60KA",
    "Current":1,
    "Weeks":{
        "NumWeeks":11,
        "FirstDate":"2014-10-18",
        "LastDate":"2015-01-03",
        "MaxPosition":1
    },
    "prevID":13364,
    "prevVidID":"9uo9oy-Eqo4",
    "nextID":13317,
    "nextVidID":"MYSVMgRr6pw"
}
An example response requesting information about a song

The response can then include the following attributes (dependent on what is available):

Title - The title of the requested song

Artist - The artist performing the song

VideoID - The YouTube ID of a video of a performance of the song

Current - The position of the song in the top40 at the week requested

NumWeeks - The total number of weeks the song is in the top40

FirstDate - The first day this song was in the top40

LastDate - The last day this song was in the top40

MaxPosition - The highest position this reached while it was in the top40

prevID/prevVidID - Song and Video ID of the previous in the top40

nextID/nextVidID - Song and Video ID of the next in the top40

This request allows you to do a search query for a specific song or artist. It requires a search term. To make this call the following request is done: GET <home-url>php/database.php?query=search&term=%TERM%&key=%KEY%. A response would be as follows: 

[
    {
        "SongID":12801,
        "Title":"The a team",
        "Artist":"Ed Sheeran",
        "YoutubeID":"UAWcs5H-qgQ",
        "Weeks":
        {"
            NumWeeks":32,
            "FirstDate":"2011-10-08",
            "LastDate":"2012-05-12",
            "MaxPosition":5,
            "WeekID":2446
        }
    },
    {
        "SongID":12878,
        "Title":"Lego house",
        "Artist":"Ed Sheeran",
        "YoutubeID":"c4BLVznuWnU",
        "Weeks":
        {
            "NumWeeks":13,
            "FirstDate":"2012-02-18",
            "LastDate":"2012-05-12",
            "MaxPosition":12,
            "WeekID":2446
        }
    }
    ...
]
An example response after a search query has been executed (response shortened to just the first two results)

The response can then include the following attributes (dependent on what is available):

SongID - The database ID of the specific song

Title - The title of the specific song

Artist - The artist performing the song

VideoID - The YouTube ID of a video of a performance of the song

NumWeeks - The total number of weeks the song is in the top40

FirstDate - The first day this song was in the top40

LastDate - The last day this song was in the top40

MaxPosition - The highest position this reached while it was in the top40

nextID - Week ID of a week during which this song was in the top40 (allowing you to call query=song after having done a search)

List

This request gathers the top 40 songs for a specific week. It requires the WeekID of the requested week. To make this call the following request is done: GET <home-url>php/database.php?query=list&week=%WEEKID%&key=%KEY%. A response would be as follows: 

[
    {
        "WeekNumber":1,
        "StartDate":"3 January 2015"
    },
    {
        "SongID":13358,
        "Title":"Thinking out loud",
        "Artist":"Ed Sheeran"
    },
    {
        "SongID":13317,
        "Title":"Take me to church",
        "Artist":"Hozier"
    }
    ...
    {
        "SongID":13364,
        "Title":"Baby don't lie",
        "Artist":"Gwen Stefani"
    }
]
An example response requesting the top 40 songs (response shortened)

The first in the array always holds the week number and start date of that specific week. The remaining forty elements are the top songs in order (i.e. [1] = #1, [40] = #40).
The response can then include the following attributes (dependent on what is available):

WeekNumber - The number of the requested week (usually between 1 and 52)

StartDate - The first day of the requested week

SongID - The database ID of the specific song

Title - The title of the specific song

Artist - The artist performing the song

Prep

This request takes a given date and returns the weekID, week number and songID of the top song at that specific time. It requires the date in the following format yyyy-mm-dd To make this call the following request is done: GET <home-url>php/database.php?query=prep&date=%DATE%&key=%KEY%. The response would be as follows: 

{
    "week":2582,
    "weeknumber":2,
    "song":13358
}
An example response requesting information on 2015-01-12

The response can then include the following attributes (dependent on what is available):

week - The weekID of that week

song - The ID of the number one song at that time