-
Notifications
You must be signed in to change notification settings - Fork 34
Getting Started
The Last.fm API bindings for Java are a BSD licensed API providing a Java interface to the Last.fm web services. The API contains the following features:
- Invoke any of the Last.fm API methods documented here
- Scrobble songs to a Last.fm profile
- Tuning into a Last.fm radio station
- Caching of the data returned by the API methods
The API requires at least Java 1.5. To use the API add the lastfm-bindings.jar to your classpath or grab the dependency via Maven/Gradle (de.u-mass:lastfm-java:0.1.2). You can then find the API classes in the de.umass.lastfm package. Before you can use the Last.fm APIs you'll have to obtain an API key from here.
Before you invoke any methods you must set a user-agent string via:
Caller.getInstance().setUserAgent(userAgent);
or use "tst" as user-agent while developing (which is the default if you don't specify one).
While developing you may enable debug mode for troubleshooting possible problems that may arise from the API:
Caller.getInstance().setDebugMode(true);
The bindings provide standard proxy support. You can set a proxy via:
Caller.getInstance().setProxy(myProxy);
which will be used in all HTTP calls, including those for scrobbling.
API method bindings are available via the static methods in the classes named Artist, Track, User and the like. The Java class and method names follow the conventions of the Last.fm API, that means you can find the method user.getRecentTracks in the class User with the method name getRecentTracks, which takes the same parameters as the REST method documented in the link above plus your API key. An example for a method call looks like that:
String key = "b25b959554ed76058ac220b7b2e0a026"; //this is the key used in the Last.fm API examples
String user = "JRoar";
Chart<Artist> chart = User.getWeeklyArtistChart(user, 10, key);
DateFormat format = DateFormat.getDateInstance();
String from = format.format(chart.getFrom());
String to = format.format(chart.getTo());
System.out.printf("Charts for %s for the week from %s to %s:%n", user, from, to);
Collection<Artist> artists = chart.getEntries();
for (Artist artist : artists) {
System.out.println(artist.getName());
}
Calls that require authentication require a Session parameter. Sessions can be obtained via the Authenticator class. See here for different authentication methods. An example for a authenticated method call looks like that:
String key = "..."; // api key
String secret = "..."; // api secret
String user = "..."; // user name
String password = "..."; // user's password
Session session = Authenticator.getMobileSession(user, password, key, secret);
Playlist playlist = Playlist.create("example playlist", "description", session);
Requests that fail because of bad authentication or bad parameters (bad artist, album or track names) will return either a null value or an empty Collection. Use Caller#getLastResult() to retrieve the Result object for the last call you made to find out more in depth information about the error occurred.
Some methods return a PaginatedResult instead of a plain Collection, for example geo.getEvents. In this case you can access the data you're looking for via the PaginatedResult#getPageResults() method. Call Geo#getEvents() subsequently with incremented page numbers to load all pages if necessary. Note that page numbers start with 1 not 0.
All getXXXChart methods return an instance of Chart, instead of a plain Collection, for example user.getWeeklyArtistChart. You can access the data you're looking for via the Chart#getEntries() method.
Authenticated write calls, such as artist.share don't return any data. These methods will return an instance of the Result class, which contains an error code and error message and/or an HTTP error code for debugging, if the call failed. Otherwise Result#isSuccessful() will return true.
Please refer to the Scrobbling wiki page.
Please refer to the Radio Streaming wiki page.
The Last.fm API Terms of Service require:
4.4 You will implement suitable caching in accordance with the HTTP headers sent with web service responses. You will not make more than 5 requests per originating IP address per second, averaged over a 5 minute period, without prior written consent. You agree to cache similar artist and any chart data (top tracks, top artists, top albums) for a minimum of one week.
Therefore the bindings are capable of caching data returned by the APIs. Cache management is implemented in the de.umass.lastfm.cache package and the Caller#setCache() method. By default there is a FileSystemCache activated which will cache the Last.fm data in a directory on your file system (by default <user home dir>/.last.fm-cache). In addition there is an ExpirationPolicy interface which defines the expiration date for cached data if no expiration HTTP headers were sent. If you want to cache to a Database you can use the de.umass.lastfm.cache.DatabaseCache class. Note that the API bindings do not protect you from violating against the 5-requests-per-second limit. Scheduling and optimising your API calls so that your app complies to the TOS is your responsibility.