Wikia

Wikia API Wiki

LyricWiki API/SOAP

Comments4
25pages on
this wiki

< LyricWiki API

Cropped Lyrics Edit

Please note that currently, the API only returns a small portion of the lyrics (about 1/7th of them). This is because of the licensing restrictions mentioned in the Google Group thread. The small snippet (which is considered Fair Use) is just to help in identifying that the API matched the correct song you're looking for.

IntroEdit

If we make backwards-incompatible changes or updates to the API, we will inform developers via the Google Group mailing list. We do NOT spam the list (you can see from the link that the volume is very low... about one email per year).

Google Groups
Subscribe to LyricWiki API Developers
Email:
Visit this group

The LyricWiki SOAP web service API uses a server written with nuSOAP for PHP, but follows the WSDL standard so that any system that uses WSDL files can easily access the web service. Some languages/environments that are known to easily integrate using WSDL files are PHP (using the nusoap package), Java, and .NET (C#). The functionality is not done for the server yet, but it exists and will return default values that may help in testing during your development of extensions (the server should be done in a matter of days).

Once the server is finished, a PHP file will be made available that wraps the web service into a few simple functions so that you can use the web service by simple calling functions as if they were on your local machine. The early predecessor of this file is the SOAP client test-script (it is a good example of PHP code which uses the SOAP API).

The WSDL file can be found here.

Basic documentation for the web-service (not the PHP file that will wrap it) can be found here.

UPDATE April 2, 2007: We added a return value for the url to getSong() and getSongResult(), since the page name may differ from what would be expected by the request (due to redirects, etc.), this should be used instead of URLs you generate yourself since it reflects our naming conventions and the current state of the database.

Portability TestingEdit

Tested on

  • PHP (PHP5 SOAP Library) - Works PHP5's built in SOAP Library works.
  • PHP (nuSOAP) - Works (see external links)
  • PHP (WSF/PHP) - Works Small PHP library written using WSF/PHP [1]
  • .NET framework 2.0 and 3.0 - Works (Except for a few Functions)
    • Testing by adding a web reference and running CheckSongExists() & getSong(). Both work great!. getArtist() don´t works.
  • Perl- Works Perl module for fetching lyrics by Dave P available on CPAN
  • Flash - Partially tested : The crossdomain.xml file has been added to the root directory so that the security warning is not displayed to users. Since 'return' is a reserved word in flash, getSongResult() should be used instead of getSong().
  • Python - Partially tested : Using ZSI.
  • SOAPpy - Bugs : has a problem with the content-type header. Spews an error (but recieves the lyrics if you put debug output on this can be seen).
  • SUDS - Works: Using lightweight library. "from suds.client import Client; c = Client('http://lyrics.wikia.com/server.php?wsdl'); print c.service.getSong(name, song)"
  • Ruby - Bugs : Any character outside of ASCII is returned malformatted. See talk page.
  • Java & Axis - Unknown : The WSDL file does not work as provided, but a fix (setting namespace for array types in two places) can be performed to make it work. See talk page.
  • Javascript - Uses the alternative REST version. Please note that this is the exact same backend code with a different frontend.
  • AppleScript: works fine with the "call soap" api, for getSong(). Some problems may occur with accentuation (french, spanish...)

Current ProgressEdit

Currently the WSDL file works and the following methods are working: (note: SOTD is short for Song of the Day)

  • checkSongExists()
  • getSong()
  • getSongResult() - an alias for getSong() which returns the value as 'songResult' instead of 'return' since 'return' is a reserved word in flash.
  • getSOTD()
  • getArtist() - also works with api.php (use func=getArtist at the end of the url to use this function. ex: [2]).
  • getHometown()
  • postAlbum()
  • postSong()

AuthenticationEdit

Since anonymous users are allowed to edit LyricWiki, they are also allowed to use the SOAP webservice to make changes. However, if you would like to associate any SOAP webservice changes that you make with your user-account, this can easily be achieved by setting the SOAP headers 'username' and 'password'. If you are using nuSOAP (PHP), here is an example of how to do this:

$LW_USERNAME = "your_username_here";
$LW_PASSWORD = "your_password_here";
require_once('nusoap.php');
$client = new soapclient('http://lyrics.wikia.com/server.php?wsdl', true);
$err = $client->getError();
if ($err) {
	echo '<h2>Constructor error</h2><p>' . $err . '</p>';
} else {
	$proxy = $client->getProxy();
	if(($LW_USERNAME != "") && ($LW_PASSWORD != "")){
		$headers = "<username>$LW_USERNAME</username><password>$LW_PASSWORD</password>\n";
		$proxy->setHeaders($headers);
	}
}

Allowed Requests/ResponsesEdit

I will be adding amazon links (throw them out if you don't want them) and some other Request/Response pairs. Stay tuned.

There are two types of ways to push updates to LyricWiki. Make[x] and Update[x]. When using Make[x], if the item already exists, the update is not applied, and an error is returned. This is considered safer and should be used any time you are adding completely new items, even if you have already used the API to check if the item exists. When using Update[x], the item is created/changed regardless of whether it existed previously. If the page did not exist previously, a warning is returned in the 'Message' tags.

FetchingEdit

  • getSong
    • artist
    • song
  • getSongResponse
    • return [type: LyricsResult]
        • artist
        • song
        • lyrics
        • url



  • getArtist
    • artist
  • getArtistResponse
    • artist
    • albums [type: AlbumDataArray]
      • item [type: AlbumData] (0 or more)
        • album
        • year
        • amazonLink
        • songs [type: ArrayOfstring]
          • item (0 or more)
          • ..item
          • ..item
      • ..item
      • ..item



  • getAlbum
    • artist
    • album
    • year (optional)
  • getAlbumResponse
    • artist
    • album
    • year
    • amazonLink
    • songs [type: ArrayOfstring]
      • item (0 or more)
      • ..item
      • ..item



  • getHometown
    • artist
  • getHometownResponse
    • country
    • state
    • hometown



  • getSOTD
  • getSOTDResponse
    • artist
    • song
    • nominatedBy
    • reason
    • lyrics

Updating PagesEdit

  • postArtist
    • overwriteIfExists {true,false} (defaults to false, please use false in most cases)
    • artist
    • albums [type: AlbumArray]
      • item [type: Album] (0 or more)
        • album
        • year
        • amazonLink (please just provide the ASIN in this case)
        • songs [type: ArrayOfstring]
          • item (0 or more)
          • ..item
          • ..item
      • ..item
      • ..item
  • postArtistResponse
    • artist
    • dataUsed {true,false} if this is false, check the contents of message. if overwriteIfExists is false, and the artist already existed, this will return false
    • message



  • postAlbum
    • overwriteIfExists {true,false} (defaults to false, please use false in most cases)
    • artist
    • album
    • year
    • asin
    • songs [type: ArrayOfstring]
      • item (0 or more)
      • ..item
      • ..item
  • postAlbumResponse
    • artist
    • album
    • year
    • dataUsed {true,false} if this is false, check the contents of message. if overwriteIfExists is false, and the artist already existed, this will return false
    • message



  • postSong
    • overwriteIfExists {true,false} (defaults to false, make sure to set to true if updating already existing lyrics)
    • artist
    • song
    • lyrics
    • onAlbums [type: AlbumResultArray]
      • item (0 or more)
        • artist (if left blank, defaults to the artist of the current song)
        • album
        • year
      • ..item
      • ..item
  • postSongResponse
    • artist
    • song
    • dataUsed {true,false} if this is false, check the contents of message. if overwriteIfExists is false, and the artist already existed, this will return false
    • message

Future TasksEdit

  • Allow the webservice to post/retrieve album art given the Song or the Album (don't require the album, figure that out automatically). Refer to this article.
  • Normalise CaPiTaLiSaTiOn - again, people are naming pages inconsistently and this should be handled in the search (either by searching all lower case or UPPER CASE). i.e. a case-insensitive search (again to be implemented server side to speed this up).
  • Allow lookups of pages other than songs/artists etc. For example, it would be useful to be able to view the pages listing songs in a particular language or in need of language identification. However, since these pages are automatically indexed, modifying them directly is not desirable. This can be done using the default MediaWiki APIs, but those need to be fixed to work on the same domain as our API.
  • Make the REST code actually RESTful (with meaningful error messages).
  • Make the XML more well-structured.
  • Have the name of the client-program passed in so that we can work with developers to figure out problems when things are going strangely.

Related LinksEdit

  • REST-like API (REpresentational State Transfer) - alternate method of accessing the API using these same functions but making requests via HTTP "GET" requests. The actual implementation is somewhere between REST and XML-RPC (Remote Procedure Calls).
  • Failed SOAP requests - This lists contains the 50 most commonly failed requests. It helps find highly-desired missing songs/artists/redirects and shows us ways that we could improve the searching ability of the SOAP.
  • Failed SOAP requests - List containing the most commonly failed requests which come from the LyricWiki mobile app.
  • LyricWiki Apps - List of plugins, sites, apps, etc. that implement use the LyricWiki API. Please add your own application once it is complete.

External LinksEdit

SOAP on Wikipedia.
nuSOAP tutorial whose code was used to build the server and test-client.
Generic SOAP Client for testing.
WSDL Essentials chapter from Web Services Essentials.
Tutorial - Creating and Consuming Web Services with PHP
Tutorial that uses complex types in writing the web service (more for server work than client-side).
Tutorial write your first lyrics lookup using .NET (C# and others).
Tutorial (also server-side).

Around Wikia's network

Random Wiki