NAME
WebService::Upcoming - Perl interface to the Upcoming API
SYNOPSIS
use WebService::Upcoming;
my $upco = new WebService::Upcoming(
"*** UPCOMING API KEY HERE ***");
my $objc = $upco->call("event.search",
{
"search_text" => "music"
});
die("ERROR: ".$upco->err_text()."\n") if (!defined($objc));
foreach (@{$objc})
{
print("EVENT: ".$_->name()." on ".$_->start_date()."\n");
}
DESCRIPTION
A simple interface for using the Upcoming API.
WebService::Upcoming
is a subclass of LWP::UserAgent, so all of the various proxy, request limits, caching, and other features are available.
METHODS
new($key [, $version ])
-
Creates an
WebService::Upcoming
object. $key is the API key used to identify the client to the Upcoming server. $version is the version of the Upcoming API to call, and it defaults to "1.0" if excluded.API keys may be obtained from http://upcoming.org/services/api/keygen.php.
key( [ $key ] )
-
Sets or retrieves the current API key.
call($method, \%args)
-
Constructs and executes a request to upcoming.org, returning an array of objects that define the response.
$method defines the Upcoming API method to call. \%args is a reference to a hash containing arguments to the method.
Each call() returns a reference to an array of
WebService::Upcoming::Object::*
objects, depending on the request. event.getInfo, for instance, will returnWebService::Upcoming::Object::Event
objects, with methods for each attribute: id(), name(), description(), etc. Empty arrays can also be returned, indicating a successful call(), but without any response, such as watchlist.remove.On failure, call() returns undef. HTTP error codes are available through $upco->err_code(), human-readable error text is available through $upco->err_text().
Version 1.0 of the Upcoming API includes the following objects, all represented in the Perl namespace
WebService::Upcoming::Object
: Category, Country, Event, Metro, State, User, Venue and Watchlist.For a list of methods, their arguments and what object to expect in response, see http://www.upcoming.org/services/api/. For each XML response in the Upcoming documentation, the attributes are available through methods of the same name on the
WebService::Upcoming::Object::*
objects. err_code()
-
Returns the last HTTP error code. Only valid if call() returns undef.
err_text()
-
Returns the last human-readable error text. Only valid if call() returns undef.
AUTHOR
Copyright (C) 2005, Greg Knauss, <greg@eod.com>
SEE ALSO
http://www.upcoming.org/, http://www.upcoming.org/services/api/