Turnkey Solution Automatic links XML Catalog Webservice

Create Affiliate ID

Code samples below do not contain a valid Affiliate ID. Create an Affiliate account before using these.

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:

Entities

You can access 3 entities through the webservice:

Artist

The artist entity represents the artist associated with a song:

Field
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
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 & Quiz).

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
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 & Quiz:

wmv

Windows Media Video.

mp4

MP4 file.

cdg

Karaoke CDG file.

kfn

KaraFun Format.

Guitar Backing Tracks:

ngt-voc

Guitar Backing Tracks with vocals.

ngt

Guitar Backing Tracks 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 its ID:

Inputs

Field
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
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
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
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
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
totalLength
integer

The total number of songs in the database.

length
integer

The number of songs found with your 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
limit
integer

[default: 10] [max: 100] The maximum number of results.

offset
integer

[default: 0] The offset of the results.

Outputs

Field
totalLength
integer

The total number of songs in the database.

length
integer

The number of songs found with your 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 an songfile with its ID:

Inputs

Field
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 following your inputs:

Inputs

Field
songId
integer

[required] Unique ID number of the song you want the files.

Outputs

Field
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
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
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):

Title

Copied!


                    {
                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:

Title

Copied!


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

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


            Api status code: 4040
            HTTP status code: 406
            API message: 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.

4061: mandatory parameter missing


            Api status code: 4061
            HTTP status code: 406
            API message: Missing mandatory argument

This error can occur with the "get" function or "list" for "songfile", where some parameters are mandatory.

4062: argument does not have the good type


            Api status code: 4062
            HTTP status code: 406
            API message: A given argument does not have the good type

This error can occur when parameters don't have the expected type.

Example of error

Request


                    {
                affiliateId: 77,
                function: "get"
            }}
            URL: https://www.karaoke-version.com/api/artist/
            // https://www.karaoke-version.com//api/artist/?query=%7B%22affiliateId%22%3A77%2C%22function%22%3A%22get%22%7D

Response


                    {
                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 ID is 77 and you use US URL of the service.

Artist List

You want to have the list of all the artists. You should perform the following request:


                           
            {
              affiliateId:77,
              function: "list"
            }
            URL:https://www.karaoke-version.com/api/artist/

In order to comply with URL encoding the request should be:

https://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: https://www.karaoke-version.com/api/song/

In order to comply with URL encoding the request should be:

https://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: https://www.karaoke-version.com/api/song/

In order to comply with URL encoding the request should be:

https://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

Title


                           
            {
              affiliateId: 77,
              function: "song",
              parameters: {
                query: "madonna"
              }
            }
            URL: https://www.karaoke-version.com/api/search/

In order to comply with URL encoding the request should be:

https://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: https://www.karaoke-version.com/api/song/

In order to comply with URL encoding the request should be:

https://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

Top 5 Artists

Five most popular artists:


                           
           {
              affiliateId: 77,
              function: "list",
              parameters: {
                limit: 5
              }
            }
            URL: https://www.karaoke-version.com/api/artist/

In order to comply with URL encoding the request should be:

https://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

Here you can find the 10 latest songs:


                           
           {
              affiliateId: 77,
              function: "listLatestAdded",
              parameters: {
                limit: 10
              }
            }
            URL: https://www.karaoke-version.com/api/song/

In order to comply with URL encoding the request should be:

https://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