LYRDB Web Services

Technical details

If you don't like to implement the LYRDB Web Services, you can use some of the current tested implementations for Visual Basic and ASP. Please visit the developers resources.

Currently we offer database access through an HTTP interface.

We are going to talk about two processes: Searching for lyrics and Retrieving lyrics. Don't forget to read about the Errors.

If you like to collaborate with this project, please implement the lyrics submission service, to allow this free and open database to grow.

Searching for lyrics

To search for lyrics, fetch the following resource:

http://www.lyrdb.com/lookup.php?q=query&for=field&agent=agent

Basically you have 3 parameters to send:

q (query): escaped query, what you want to search.
for (field): type of search do you want.
agent: the name of your program, service, etc. Although this parameter is optional, please specify it. Examples: "LyricsDownloader/2.3", "MusicPlay/1.0", "MySoft"...

The query parameter varies with the field. The allowed values for "field":

"trackname": Query represents the exact name of the song name or the exact beginning of the song name. Matched results will be returned.
"artist": Query represents the exact name of the artist/band or the exact begginning of the artist. If your query is "Elton John", lyrics for "Elton John", "Elton John feat. artist", "Elton John with artist" will be returned, for example.
"match": Query must be "artist|trackname". "|" is a vertical bar character and there aren't spaces around the vertical bar. Artist and Trackname must be supplied in the specified order or no results will be matched.
"inlyrics": Query represent part of the song lyrics. Query may be separate words, a full verse... A maximum of 50 lyrics will be returned, ordered by relevance, being the first the one with more relevance.
"fullt": Query represent a flexible string with enough information (trackname and/or artist, part of them) to identify the lyrics. Examples: "Simply Red - Sunrise", "Sunrise - Simply Red", "Sunrise (Home) - Simply Red", "Simply Red - Sunrise (feat. artist)". A maximum of 50 lyrics will be returned, ordered by relevance. "Fullt" is certainly a great way of matching results when metadata from MP3 is not very accurate, or you have the song title in a non-standard format. Note that in the query string should be enough information (the keywords order doesn't matter, or if there are more keyword than needed).

The lookup returns matched lyrics in text format. For instance, if we lookup for "we are the champions" and we look for "trackname", that resultset will be returned:

109072\We Are The Champions\GEMINI
205305\We Are The Champions\Queen
4416\We Are The Champions\A Knight's Tale
a00022723\We Are The Champions\GREEN DAY
s00218106\We Are The Champions\Five Queen
s00226904\We Are The Champions\Freddie Mercury
s00234885\We Are the Champions\Gemini
s00249593\We Are The Champions\Green Day
s00463942\We Are The Champions\Queen
s00482456\We Are The Champions\Robbie Williams
s00533461\We Are The Champions\State Property
s00628183\We Are The Champions\Williams Robbie
t00025526\We Are The Champions\Queen
t00043036\We Are The Champions\Robbie Williams
t00171468\We Are The Champions\Zucchero
t00279439\We Are The Champions\Charlotte Church
t00427345\We Are the Champions\Freddie Mercury
t00447643\We Are The Champions\Green Day
t00455455\We Are The Champions\Kamikase

Lines are separated by CR-LF 2 byte characters (chr(13)+chr(10)). 3 fields are returned per line and are separated by inverse slash (\). No other inverse slashes are present in the individual fields.

First field is an unique 9 digit (max) identifier. When you want to retrieve lyrics, you have to pass this identifier (ID).
Second field is the track name.
Third field is the artist/band.

You may want to use the split function in VB languages or explode in PHP, for example, to separate lines and fields into arrays.

Retrieving lyrics

Retrieving lyrics is as easy as fetching the following resource:

http://www.lyrdb.com/getlyr.php?q=id

The "q" parameter contains the LYRDB lyrics identifier provided with each result in the lookup. The lyrics are returned as they are in the database. Lines may be separated by LF or CRLF characters, as they were sent by the user. To display them, you may want to unify line separators and trim lyrics for spaces, tabs or line feeds.

Errors

Error may arise from queries to the database (may be your fault, or database issues). If there was an error, returned string is:

error:#num#
Error description

#num# is a error code (only for quick identification process). Below that line (with a CRLF pair of bytes), there is a textual error description. Error messages are self explanatory:

Error code	Cause
Errors for lookup.php
i101	Database connection problem (nearly impossible to appear)
100	"for" parameter contains an invalid field
i102	Database query problem (as error i101, nearly impossible to appear)
Errors for getlyr.php
i101	Database connection problem (nearly impossible to appear)
102	"id" parameter invalid or empty
101	No such a entry in the database for specified "id"
103	Bandwidth quota exceeded. There is a bandwidth control to prevent users to download massive lyrics with the LYRDB Web Services. Currently, there is an allowed bandwidth of 20 MB of lyrics per day (that is, nearly 14.000 lyrics per day, that is OK, no?).

Lyrics submissions

If you use the LYRDB Web Services, you like to find the lyrics you are looking for. So, please, if applicable, put a lyrics submission form so that you or your users will be able to submit the lyrics that you don't find.

To test your implementation, please read this.

To submit lyrics, POST the following fields to the URL:

http://www.lyrdb.com/uploadlyr.php

Field	Optional?	Expected value
name	Optional	The name of the user who submitted the lyrics.
email	Optional	The e-mail address of the user who submitted the lyrics (e.g. "user@host.com").
allowemail	Optional	A boolean value ("y" or "n") specifying if the user e-mail address should be shown in the LYRDB.com website. Default NO ("n").
artist	Mandatory	The lyrics' artist/band name.
trackname	Mandatory	The lyrics' title.
lyrics	Mandatory	The lyrics text. The line breaks can be in CRLF form (Windows) or LF form (Linux/Unix).
agent	Mandatory	A string with the name and the version of the software which is sending the lyrics. e.g "SoftwareName/1.0", "MySoft v1.x", etc. This string is only for statistical purposes or, in case of service abuse, to identify the spammer.

Remember to encode the field contents! Also, remember to add the "Content-type" header:

Content-Type: application/x-www-form-urlencoded

The POST headers should look something like this (all in the same line):

name=Flavio+Gonz%E1lez+V%E1zquez
&email=flavio%40ya.com
&allowemail=y
&artist=Simply+Red
&trackname=Sunrise
&lyrics=lyrics+line1%0D%0Alyrics+line2
&agent=Example%2F1.0

Once we receive the lyrics, we manually approve them within 1/2 days (depends of the amount of lyrics that we receive).

If you want to test your implementation, please contact me at flavio@ya.com (my name is Flavio) and we can arrange to meet one day to test your implementation. Don't expect the lyrics you submit to appear automatically at LYRDB since I manually approve all submission.