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.com/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:

PHP class to use our webservice View and download
Top 10 View in action and download
Search View in action and download
Artist List View in action and download

Entities

You can access 3 entities through the webservice:

Artist

The artist entity represents the artist associated with a song:

Field	Data type	Description
id	integer	Unique artist number ID
name	string	The name of the artist
nameSorted	string	The name of the artist with the last name first.
url	string	Link to the page of the artist on Karaoke Version

Song

The song entity includes information about songs:

Field	Data type	Description
id	integer	Unique ID number of the song
artistId	integer	Unique ID number of the artist that performed that song
name	string	The name of the song
url	string	Link to the page of the song on Karaoke Version
previewUrl	string	Link to the preview of the song on Karaoke Version (mp3 or mp4 file)
imageUrl	string	Link to the illustration of the song (jpeg image)
mp3Count	integer	Count of mp3 filerelated to this song
wmvCount	integer	Same but for WMV file (video Karaoke)
cdgCount	integer	Same but for CDG file (MP3+G)
hasMulti	bool	Whether the song has custom backing track or not
multiUrl	string	Link to the page of the song's custom backing track on Karaoke Version
dateAdded	string	Date of creation of this song (MySQL DateTime format)

SongFile

The songfile entity includes information about file for each song:

Field	Data type	Description
id	integer	Unique ID number of the songfile
songId	integer	Unique ID number of the song
artistId	integer	Unique ID number of the artist that performed that song
songUrl	string	Link to the page of song on Karaoke Version in the corresponding section (depending on its track type)
previewUrl	string	Link to the preview of the song on Karaoke Version (mp3 or mp4 file)
format	string	Format 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
price	float	Price of the file
currency	string	Currency 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

Field	Data type	Description
id	number	[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

Field	Data type	Description
id	array	An array of unique ID numbers of the artists you want
limit	integer	[default: 10] [max: 100] The limit of results
offset	integer	[default: 0] The offset for the results.

Outputs

Field	Data type	Description
totalLength	integer	The total number of artists in the database
length	integer	The number of artists found with you inputs
artists	array	An 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

Field	Data type	Description
id	number	[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

Field	Data type	Description
id	array	An array of unique ID numbers of the songs you want
artistId	array	An array of unique ID numbers of the song's artists you want
limit	integer	[default: 10] [max: 100] The limit of results
offset	integer	[default: 0] The offset for the results.
dateAdded	object	min: the minimum dateAdded of the songs you want max: the maximum dateAdded of the songs you want

Outputs

Field	Data type	Description
totalLength	integer	The total number of songs in the database
length	integer	The number of songs found with you inputs
songs	array	An 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

Field	Data type	Description
limit	integer	[default: 10] [max: 100] The maximum number of results
offset	integer	[default: 0] The offset of the results

Outputs

Field	Data type	Description
totalLength	integer	The total number of songs in the database
length	integer	The number of songs found with you inputs
songs	array	An 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

Field	Data type	Description
id	number	[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

Field	Data type	Description
songId	integer	[required] Unique ID number of the song you want the files

Outputs

Field	Data type	Description
length	integer	The number of songfiles of the given song
songfiles	array	An 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

Field	Data type	Description
query	string	[required] What you search
limit	integer	[default: 10] [max: 100] The limit of results
offset	integer	[default: 0] The offset for the results.

Outputs

Field	Data type	Description
length	integer	The number of songs found
songs	array	An 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: artist/
song: /song/
songfile: songfile/
search: 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.