WebService::Upcoming - Perl interface to the Upcoming API
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"); }
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.
WebService::Upcoming
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 return WebService::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.
WebService::Upcoming::Object::*
WebService::Upcoming::Object::Event
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.
WebService::Upcoming::Object
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.
query($method, \$args)
Constructs and executes a request to upcoming.org, returning the XML response.
See <call()> for details.
parse($method, $response)
Parses an API response from upcoming.org, returning an array of objects that define the response.
$method defines the Upcoming API method that generated the response. $response is the XML sent by the server.
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.
Copyright (C) 2005, Greg Knauss, <greg@eod.com>
http://www.upcoming.org/, http://www.upcoming.org/services/api/
To install WebService::Upcoming, copy and paste the appropriate command in to your terminal.
cpanm
cpanm WebService::Upcoming
CPAN shell
perl -MCPAN -e shell install WebService::Upcoming
For more information on module installation, please visit the detailed CPAN module installation guide.