LYRDB Web Services
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.
If you like to collaborate with this project, please implement the lyrics submission service, to allow this free and open database to grow.
To search for lyrics, fetch the following resource:
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 is as easy as fetching the following resource:
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.
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:
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?).|
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:
|name||Optional||The name of the user who submitted the lyrics.|
|Optional||The e-mail address of the user who submitted the lyrics (e.g. "email@example.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).|
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:
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
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 firstname.lastname@example.org (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.