de.umass.lastfm
Class Geo

java.lang.Object
  extended by de.umass.lastfm.Geo

public class Geo
extends Object

Provides nothing more than a namespace for the API methods starting with geo.

Author:
Janni Kovacs

Nested Class Summary
static class Geo.Metro
          This inner class represents a Metro, which is composed of its name and the name of its country.
 
Method Summary
static Collection<Event> getAllEvents(String location, String distance, String apiKey)
          Get all events in a specific location by country or city name.
This method returns all events by subsequently calling getEvents(String, String, int, String) and concatenating the single results into one list.
Pay attention if you use this method as it may produce a lot of network traffic and therefore may consume a long time.
static PaginatedResult<Event> getEvents(double latitude, double longitude, int page, String apiKey)
          Get all events in a specific location by country or city name.
This method only returns the specified page of a paginated result.
static PaginatedResult<Event> getEvents(String location, String distance, int page, String apiKey)
          Get all events in a specific location by country or city name.
This method only returns the specified page of a paginated result.
static PaginatedResult<Event> getEvents(String location, String distance, String apiKey)
          Get all events in a specific location by country or city name.
This method only returns the first page of a possibly paginated result.
static Chart<Artist> getMetroArtistChart(Geo.Metro metro, String start, String end, String apiKey)
           
static Chart<Artist> getMetroArtistChart(String country, String metro, String apiKey)
           
static Chart<Artist> getMetroArtistChart(String country, String metro, String start, String end, String apiKey)
           
static Chart<Artist> getMetroHypeArtistChart(Geo.Metro metro, String start, String end, String apiKey)
           
static Chart<Artist> getMetroHypeArtistChart(String country, String metro, String apiKey)
           
static Chart<Artist> getMetroHypeArtistChart(String country, String metro, String start, String end, String apiKey)
           
static Chart<Track> getMetroHypeTrackChart(Geo.Metro metro, String start, String end, String apiKey)
           
static Chart<Track> getMetroHypeTrackChart(String country, String metro, String apiKey)
           
static Chart<Track> getMetroHypeTrackChart(String country, String metro, String start, String end, String apiKey)
           
static Collection<Geo.Metro> getMetros(String apiKey)
          Get a list of valid countries and Geo.Metros for use in the other webservices.
static Collection<Geo.Metro> getMetros(String country, String apiKey)
          Get a list of valid countries and Geo.Metros for use in the other webservices.
static Chart<Track> getMetroTrackChart(Geo.Metro metro, String start, String end, String apiKey)
           
static Chart<Track> getMetroTrackChart(String country, String metro, String apiKey)
           
static Chart<Track> getMetroTrackChart(String country, String metro, String start, String end, String apiKey)
           
static Chart<Artist> getMetroUniqueArtistChart(Geo.Metro metro, String start, String end, String apiKey)
           
static Chart<Artist> getMetroUniqueArtistChart(String country, String metro, String apiKey)
           
static Chart<Artist> getMetroUniqueArtistChart(String country, String metro, String start, String end, String apiKey)
           
static Chart<Track> getMetroUniqueTrackChart(Geo.Metro metro, String start, String end, String apiKey)
           
static Chart<Track> getMetroUniqueTrackChart(String country, String metro, String apiKey)
           
static Chart<Track> getMetroUniqueTrackChart(String country, String metro, String start, String end, String apiKey)
           
static LinkedHashMap<String,String> getMetroWeeklyChartList(String metro, String apiKey)
          Get a list of available chart periods for this metro, expressed as date ranges which can be sent to the chart services.
static Collection<Artist> getTopArtists(String country, String apiKey)
          Get the most popular artists on Last.fm by country
static Collection<Track> getTopTracks(String country, String apiKey)
          Get the most popular tracks on Last.fm by country
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

getAllEvents

public static Collection<Event> getAllEvents(String location,
                                             String distance,
                                             String apiKey)
Get all events in a specific location by country or city name.
This method returns all events by subsequently calling getEvents(String, String, int, String) and concatenating the single results into one list.
Pay attention if you use this method as it may produce a lot of network traffic and therefore may consume a long time.

Parameters:
location - Specifies a location to retrieve events for
distance - Find events within a specified distance
apiKey - A Last.fm API key.
Returns:
a list containing all events

getEvents

public static PaginatedResult<Event> getEvents(String location,
                                               String distance,
                                               String apiKey)
Get all events in a specific location by country or city name.
This method only returns the first page of a possibly paginated result. To retrieve all pages get the total number of pages via PaginatedResult.getTotalPages() and subsequently call getEvents(String, String, int, String) with the successive page numbers.

Parameters:
location - Specifies a location to retrieve events for
distance - Find events within a specified distance
apiKey - A Last.fm API key.
Returns:
a PaginatedResult containing a list of events

getEvents

public static PaginatedResult<Event> getEvents(String location,
                                               String distance,
                                               int page,
                                               String apiKey)
Get all events in a specific location by country or city name.
This method only returns the specified page of a paginated result.

Parameters:
location - Specifies a location to retrieve events for
distance - Find events within a specified distance
page - A page number for pagination
apiKey - A Last.fm API key.
Returns:
a PaginatedResult containing a list of events

getEvents

public static PaginatedResult<Event> getEvents(double latitude,
                                               double longitude,
                                               int page,
                                               String apiKey)
Get all events in a specific location by country or city name.
This method only returns the specified page of a paginated result.

Parameters:
latitude - Latitude
longitude - Longitude
page - A page number for pagination
apiKey - A Last.fm API key.
Returns:
a PaginatedResult containing a list of events

getTopArtists

public static Collection<Artist> getTopArtists(String country,
                                               String apiKey)
Get the most popular artists on Last.fm by country

Parameters:
country - A country name, as defined by the ISO 3166-1 country names standard
apiKey - A Last.fm API key.
Returns:
list of Artists

getTopTracks

public static Collection<Track> getTopTracks(String country,
                                             String apiKey)
Get the most popular tracks on Last.fm by country

Parameters:
country - A country name, as defined by the ISO 3166-1 country names standard
apiKey - A Last.fm API key.
Returns:
a list of Tracks

getMetros

public static Collection<Geo.Metro> getMetros(String apiKey)
Get a list of valid countries and Geo.Metros for use in the other webservices.

Parameters:
apiKey - A Last.fm API key
Returns:
a List of Geo.Metros

getMetros

public static Collection<Geo.Metro> getMetros(String country,
                                              String apiKey)
Get a list of valid countries and Geo.Metros for use in the other webservices.

Parameters:
country - Optionally restrict the results to those Metros from a particular country, as defined by the ISO 3166-1 country names standard
apiKey - A Last.fm API key
Returns:
a List of Geo.Metros

getMetroWeeklyChartList

public static LinkedHashMap<String,String> getMetroWeeklyChartList(String metro,
                                                                   String apiKey)
Get a list of available chart periods for this metro, expressed as date ranges which can be sent to the chart services.

Parameters:
metro - The name of the metro, or null
apiKey - A Last.fm API key
Returns:
a list of available charts as a Map

getMetroArtistChart

public static Chart<Artist> getMetroArtistChart(String country,
                                                String metro,
                                                String apiKey)

getMetroArtistChart

public static Chart<Artist> getMetroArtistChart(Geo.Metro metro,
                                                String start,
                                                String end,
                                                String apiKey)

getMetroArtistChart

public static Chart<Artist> getMetroArtistChart(String country,
                                                String metro,
                                                String start,
                                                String end,
                                                String apiKey)

getMetroTrackChart

public static Chart<Track> getMetroTrackChart(String country,
                                              String metro,
                                              String apiKey)

getMetroTrackChart

public static Chart<Track> getMetroTrackChart(Geo.Metro metro,
                                              String start,
                                              String end,
                                              String apiKey)

getMetroTrackChart

public static Chart<Track> getMetroTrackChart(String country,
                                              String metro,
                                              String start,
                                              String end,
                                              String apiKey)

getMetroHypeArtistChart

public static Chart<Artist> getMetroHypeArtistChart(String country,
                                                    String metro,
                                                    String apiKey)

getMetroHypeArtistChart

public static Chart<Artist> getMetroHypeArtistChart(Geo.Metro metro,
                                                    String start,
                                                    String end,
                                                    String apiKey)

getMetroHypeArtistChart

public static Chart<Artist> getMetroHypeArtistChart(String country,
                                                    String metro,
                                                    String start,
                                                    String end,
                                                    String apiKey)

getMetroHypeTrackChart

public static Chart<Track> getMetroHypeTrackChart(String country,
                                                  String metro,
                                                  String apiKey)

getMetroHypeTrackChart

public static Chart<Track> getMetroHypeTrackChart(Geo.Metro metro,
                                                  String start,
                                                  String end,
                                                  String apiKey)

getMetroHypeTrackChart

public static Chart<Track> getMetroHypeTrackChart(String country,
                                                  String metro,
                                                  String start,
                                                  String end,
                                                  String apiKey)

getMetroUniqueArtistChart

public static Chart<Artist> getMetroUniqueArtistChart(String country,
                                                      String metro,
                                                      String apiKey)

getMetroUniqueArtistChart

public static Chart<Artist> getMetroUniqueArtistChart(Geo.Metro metro,
                                                      String start,
                                                      String end,
                                                      String apiKey)

getMetroUniqueArtistChart

public static Chart<Artist> getMetroUniqueArtistChart(String country,
                                                      String metro,
                                                      String start,
                                                      String end,
                                                      String apiKey)

getMetroUniqueTrackChart

public static Chart<Track> getMetroUniqueTrackChart(String country,
                                                    String metro,
                                                    String apiKey)

getMetroUniqueTrackChart

public static Chart<Track> getMetroUniqueTrackChart(Geo.Metro metro,
                                                    String start,
                                                    String end,
                                                    String apiKey)

getMetroUniqueTrackChart

public static Chart<Track> getMetroUniqueTrackChart(String country,
                                                    String metro,
                                                    String start,
                                                    String end,
                                                    String apiKey)