Webservice allows you to query our database in real-time. Using this way, you don't need to install any database on your website or even modify it.

Reach the webservice

Our webservice can be reached at:
  • EN: https://www.karaoke-version.com/api/
  • FR: https://www.version-karaoke.fr/api/
  • NL: https://www.karaoke-versie.nl/api/
  • ES: https://www.version-karaoke.es/api/
  • DE: https://www.karaoke-version.de/api/
  • FI: https://www.karaoke-versio.fi/api/
  • IT: https://www.versione-karaoke.it/api/
  • SV: https://www.karaoke-version.se/api/
  • PL: https://www.wersja-karaoke.pl/api/
  • UK: https://www.karaoke-version.co.uk/api/
  • BR: https://www.versao-karaoke.com/api/

Important note: results given by the webservice depends on the country. Indeed, the popularity rank of the artist or song is computed by country and not globally. So, you should use the URL of the webservice of your own country.


Real sample code:


Entities

You can access 3 entities through the webservice:

Artist

The artist entity represents the artist associated with a song:
FieldData typeDescription
idintegerUnique artist number ID
namestringThe name of the artist
nameSortedstringThe name of the artist with the last name first.
urlstringLink to the page of the artist on Karaoke Version

Song

The song entity includes information about songs:
FieldData typeDescription
idintegerUnique ID number of the song
artistIdintegerUnique ID number of the artist that performed that song
namestringThe name of the song
urlstringLink to the page of the song on Karaoke Version
previewUrlstringLink to the preview of the song on Karaoke Version (mp3 or mp4 file)
imageUrlstringLink to the illustration of the song (jpeg image)
mp3CountintegerCount of mp3 filerelated to this song
wmvCountintegerSame but for WMV file (video Karaoke)
cdgCountintegerSame but for CDG file (MP3+G)
hasMultiboolWhether the song has custom backing track or not
multiUrlstringLink to the page of the song's custom backing track on Karaoke Version
dateAddedstringDate of creation of this song (MySQL DateTime format)

SongFile

The songfile entity includes information about file for each song:
FieldData typeDescription
idintegerUnique ID number of the songfile
songIdintegerUnique ID number of the song
artistIdintegerUnique ID number of the artist that performed that song
songUrlstringLink to the page of song on Karaoke Version in the corresponding section (depending on its track type)
previewUrlstringLink to the preview of the song on Karaoke Version (mp3 or mp4 file)
formatstringFormat of the file (mp3, kfn, wmv, cdg or zip)
trackType string Type of tracks.
MP3 Instrumental Tracks:
  • nbv: Instrumental version
  • nbv-gm: Instrumental version with backing vocals
  • nbv-ld: Cover version

Karaoke:
  • wmv: Windows Media Video
  • mp4: MP4 file
  • cdg: Karaoke CDG file
  • kfn: KaraFun Format

Guitar Backing Tracks:
  • ngt-voc: Guitar Backing Track with vocals
  • ngt: Guitar Backing Track without vocals
  • ngt-gt-voc: Full Version
  • gt: Guitar Only

Drums Backing Tracks:
  • ndr-voc: Drums Backing Track with vocals
  • ndr: Drums Backing Track without vocals
  • ndr-dr-voc: Full Version
  • dr: Drums Only
pricefloatPrice of the file
currencystringCurrency of the file's price

Available functions

To get information from the webservice, you can use the following functions, depending on the kind of action you want to perform:

Artist

get

Use this function to get an artist with his ID:

Inputs

FieldData typeDescription
idnumber[required] Unique ID number of the artist you want

Outputs

If the artist has been found, the service gives you the artist as described above, in an "artist" field. If not found, the service gives you an error, as described below.

list

Use this function to get a list of artists following your inputs:
Note: artists are sorted by popularity.

Inputs

FieldData typeDescription
idarrayAn array of unique ID numbers of the artists you want
limitinteger[default: 10] [max: 100] The limit of results
offsetinteger[default: 0] The offset for the results.

Outputs

FieldData typeDescription
totalLengthintegerThe total number of artists in the database
lengthintegerThe number of artists found with you inputs
artistsarrayAn array that contains all the artists found with your inputs, ordered by popularity ascending. Each artist is an object as described above

Song

get

Use this function to get a song with its ID:

Inputs

FieldData typeDescription
idnumber[required] Unique ID number of the song you want

Outputs

If the song has been found, the service gives you the song as described above, in a "song" field. If not found, the service gives you an error, as described below.

list

Use this function to get a list of songs following your inputs:

Inputs

FieldData typeDescription
idarrayAn array of unique ID numbers of the songs you want
artistIdarrayAn array of unique ID numbers of the song's artists you want
limitinteger[default: 10] [max: 100] The limit of results
offsetinteger[default: 0] The offset for the results.
dateAddedobject
  • min: the minimum dateAdded of the songs you want
  • max: the maximum dateAdded of the songs you want

Outputs

FieldData typeDescription
totalLengthintegerThe total number of songs in the database
lengthintegerThe number of songs found with you inputs
songsarrayAn array that contains all the songs found with your inputs, ordered by popularity ascending. Each song is an object as described above

listLatestAdded

Use this function to get the list of the lastest added songs following your inputs:

Inputs

FieldData typeDescription
limitinteger[default: 10] [max: 100] The maximum number of results
offsetinteger[default: 0] The offset of the results

Outputs

FieldData typeDescription
totalLengthintegerThe total number of songs in the database
lengthintegerThe number of songs found with you inputs
songsarrayAn array that contains all the songs found with your inputs, ordered by date added descending. Each song is an object as described above

SongFile

get

Use this function to get a songfile with its ID:

Inputs

FieldData typeDescription
idnumber[required] Unique ID number of the songfile you want

Outputs

If the songfile has been found, the service gives you the songfile as described above, in a "songfile" field. If not found, the service gives you an error, as described below.

list

Use this function to get a list of songfiles of the given song:

Inputs

FieldData typeDescription
songIdinteger[required] Unique ID number of the song you want the files

Outputs

FieldData typeDescription
lengthintegerThe number of songfiles of the given song
songfilesarrayAn array that contains all the songfiles of the song. Each songfile is an object as described above

Search

song

Use this function to search a song by its title or artist name:

Inputs

FieldData typeDescription
querystring[required] What you search
limitinteger[default: 10] [max: 100] The limit of results
offsetinteger[default: 0] The offset for the results.

Outputs

FieldData typeDescription
lengthintegerThe number of songs found
songsarrayAn array that contains all the songs found with your inputs, ordered by pertinence. Each song is an object as described above

Querying the webservice

Protocol used

The service uses HTTP protocol and GET method.

Final URL

As described above, functions are given by action kind. The action kind has to be added at the end of the API URL as follow: {API_URL}{ACTION_KIND}/.

For example, if you use the US URL of the service, you have to use these final URL depending the action kind you want to perform:
  • artist: https://www.karaoke-version.com/api/artist/
  • song: https://www.karaoke-version.com/api//song/
  • songfile: https://www.karaoke-version.com/api/songfile/
  • search: https://www.karaoke-version.com/api/search/

The query

The query itself is a GET parameter in the final URL. The parameter must be named query in your queries. This parameter has to be a JSON object that represent your request.
The JSON object has to provide 2 information: your affiliate ID number and the function you want to use. Finally, your query object should like this ("parameters" depends on your request):

{
  affiliateId: "yourAffiliateIdNumber",
  function: "theFunctionYouWantToUse",
  parameters: {
    param: "paramValue"
  }
}

Error handling

If an error occurs while your request is processed, the reply is sent with the corresponding HTTP status code and the reply contains an error object that contains the API status code and the corresponding message. If your request is correct, the HTTP status code sent is 200.
Different errors are handled:

4001: "query" parameter in the URL is missing
Api status code: 4001
HTTP status code: 400
API message: Bad request, "query" parameter absent
4002: "query" parameter is not a JSON object
Api status code: 4002
HTTP status code: 400
API message: Bad request, "query" parameter is not a valid JSON object
4030: affiliate ID number missing or wrong
Api status code: 4030
HTTP status code: 403
API message: Affiliate not identified
4050: request not sent with the GET method
Api status code: 4050
HTTP status code: 405
API message: Requests have to use GET method
5000: internal error
Api status code: 5000
HTTP status code: 500
API message: Internal error
5010: function does not exists
Api status code: 5010
HTTP status code: 406
API message: Function not implemented
4040: no data found with the given ID
This error can occur with the "get" function or "list" for "songfile", when the ID given does not match a corresponding entity.
Api status code: 4040
HTTP status code: 406
API message: No data found with the given id
4061: mandatory parameter missing
This error can occur with the "get" function or "list" for "songfile", where some parameters are mandatory.
Api status code: 4061
HTTP status code: 406
API message: Missing mandatory argument
4062: argument does not have the good type
This error can occur when parameters don't have the expected type.
Api status code: 4062
HTTP status code: 406
API message: A given argument does not have the good type

Example of error

Request
{
  affiliateId: 77,
  function: "get"
}
URL: http://www.karaoke-version.com/api/artist/
    http://www.karaoke-version.com/api/artist/?query=%7B%22affiliateId%22%3A77%2C%22function%22%3A%22get%22%7D
Reply
{
  error: {
    code: 4061,
    message: "Missing mandatory argument"
  }
}
HTTP status code: 406

Some examples of our webservice uses

Here are some examples in which our webservice is used. For each one, you'll find the query object that has been submitted to our webservice in the yellow frame and the URL used just below.
In the following examples, we consider that your affiliate number is 77 and you use US URL of the service.

Artists List

You want to have the list of all the artists. You should perform the following request:
{
  affiliateId: "423",
  function: "list"
}
URL: http://www.karaoke-version.com/api/artist/
In order to comply with URL encoding the request should be:
    http://www.karaoke-version.com/api/artist/?query=%7B%22affiliateId%22%3A77%2C%22function%22%3A%22list%22%7D

Songs count

If you want to known the number of songs available on Karaoke Version:
{
  affiliateId: 77,
  function: "list",
  parameter: {
    limit: 1
  }
}
URL: http://www.karaoke-version.com/api/song/
In order to comply with URL encoding the request should be:
    http://www.karaoke-version.com/api/song/?query=%7B%22affiliateId%22%3A77%2C%22function%22%3A%22list%22%2C%22parameters%22%3A%7B%22limit%22%3A1%7D%7D

Madonna Songs

If you search songs sung by Madonna, sorted by popularity, you should perform the following request:
{
  affiliateId: 77,
  function: "list",
  parameters: {
    artistId: [2082]
  }
}
URL: http://www.karaoke-version.com/api/song/
In order to comply with URL encoding the request should be:
    http://www.karaoke-version.com/api/song/?query=%7B%22affiliateId%22%3A77%2C%22function%22%3A%22list%22%2C%22parameters%22%3A%7B%22artistId%22%3A%5B2082%5D%7D%7D

Search

{
  affiliateId: 77,
  function: "song",
  parameters: {
    query: "madonna"
  }
}
URL: http://www.karaoke-version.com/api/search/
In order to comply with URL encoding the request should be:
    http://www.karaoke-version.com/api/search/?query=%7B%22affiliateId%22%3A77%2C%22function%22%3A%22song%22%2C%22parameters%22%3A%7B%22query%22%3A%22madonna%22%7D%7D

Top 10 songs

Here you can find the 10 most popular songs:
{
  affiliateId: 77,
  function: "list",
  parameters: {
    limit: 10
  }
}
URL: http://www.karaoke-version.com/api/song/
In order to comply with URL encoding the request should be:
    http://www.karaoke-version.com/api/song/?query=%7B%22affiliateId%22%3A77%2C%22function%22%3A%22list%22%2C%22parameters%22%3A%7B%22limit%22%3A10%7D%7D

Top 5 Artists

Five most popular artists:
{
  affiliateId: 77,
  function: "list",
  parameters: {
    limit: 5
  }
}
URL: http://www.karaoke-version.com/api/artist/
In order to comply with URL encoding the request should be:
    http://www.karaoke-version.com/api/artist/?query=%7B%22affiliateId%22%3A77%2C%22function%22%3A%22list%22%2C%22parameters%22%3A%7B%22limit%22%3A5%7D%7D

10 Latest songs

{
  affiliateId: 77,
  function: "listLatestAdded",
  parameters: {
    limit: 10
  }
}
URL: http://www.karaoke-version.com/api/song/
In order to comply with URL encoding the request should be:
    http://www.karaoke-version.com/api/song/?query=%7B%22affiliateId%22%3A77%2C%22function%22%3A%22listLatestAdded%22%2C%22parameters%22%3A%7B%22limit%22%3A5%7D%7D