Webinterface documentation

The interface is nothing different than a script (for example written in PHP) on the servers of partnersites which makes it possible to find the search results in their databases. The process is described here. Furthermore you will find an example implementation for PHP.

Transferring of your requests

The script must be uploaded on your server so it is reachable in the Internet. Through every process of searching it will be accessed and the searching parameters will be forwarded via HTTP-GET, encoded in UTF-8. Such a call can look that way e.g.:

http://www.lyric.tld/songvista.php?artist=Madonna&title=Ray%20of%20light&type=all

Release formatting

Parameter	Meaning	Possible values
artist	Artist	all*
title	Title	all*
type	Result type	lyric (lyrics) translation (translations) music (chords, tabs or notes) all (all)

* contains no control characters (\n, \r, \t)

Formatting the output

The script should answer in a basic plain/text format (UTF-8 encoded) giving the results from the local search line by line (separated by the control character "\n") in the following form:

artist|title|type|URL

Overview of used fields

Field	Meaning	Possible values
artist	Artist	all*
title	Title	all*
type	Type of this entry	lyric (lyric) translation_de** (translation) music (chords, tabs or notes)
URL	Link to the entry	has to start with http:// *

the sign | must be replace with __line__, control character are not allowed (\n,\r,\t)
** after the underscore you should set the language of the translation (e.g. de,en,es,fr)

A typical request for a lyric from "Madonna" could be responded like that:

Madonna|Ray of light|lyric|http://www.lyric.tld/madonna/ray_of_light.html
Madonna|Get together|lyric|http://www.lyric.tld/madonna/get_together.html
Madonna|Like it or not|lyric|http://www.lyric.tld/madonna/like_it_or_not.html

The number of the results, should be limited to 50 which is the amount of lines Songvista will consider.

Advantages

- Visitors can always access your latest lyrics, synchronization of databases is not necessary
- People will find lyrics on your website even if they did not know before
- Fast search through tons of data because thanks to distributed the requests
- Full control for participating webmasters
- Once build, the API can also be used also for cooperation with other sites if you want it

Disadvantages

- Partnersites could respond requests without getting a visitor
- It causes some traffic (about 5 - 10 MB per day)

Comments for use of the interface

If an interface takes more than 10 seconds to respond, the request will be aborted (timeout). There will never be more than 10 requests the within 5 seconds. Also the results will be cached. A request which was searched shortly before will not be forward to the interface again.

The single results will be reported in the same order as they were returned by the interface, so they should sort them before on your own.

Implementation example

Here you will find an implementation example for the interface implemented with PHP for version 4.1.0 an above. It already offers full functionality. Normally you should only need to adjust your database connection. You can change the script as you like to.

Notice to the implementation example:
If your database does not work with UTF-8-encoding, please convert inputs and outputs accordingly. I also offer to adjust the script for free. In that case I need to know your database structure. (Screenshot or schema in plain text)